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The Integrated Circuits 


1.1 The 68000 Processor 


The 68000 microprocessor is the heart of the entire Atari ST system. This 
16-bit chip 1s in a class by itself; programmers and hardware designers alike 
find the chip very easy to handle. From its initial development by Motorola 
in 1977 to its appearance on the market in 1979, the chip was to be a 
competitor to the INTEL 8086/8088 (the processor used in the IBM-PC and 
its many-clones). Before the Atari ST's arrival on the marketplace, there 
“were no affordable 68000 machines available to the home user. Now, 
though, with 16-bit computers becoming more affordable to the common 
man, the 8-bit machines won't be around much longer. 


What does the 68000 have that's so special? Here's a very incomplete list 
of features: 


16 data bits 

24 address bits (16-megabyte address range!!) 
all signals directly accessible without multiplexer 
hassle-free operation of "old" 8-bit peripherals 
powerful machine language commands 
easy-to-learn assembler syntax 

14 different types of addressing 

17 registers each having 32-bit widths 


These specifications (and many yet to be mentioned here) make the 68000 
an incredibly good microprocessor for home and personal computers. In 
fact, as the price of memory drops, you'll soon be seeing 68000-based 64K 
machines for the same price as present-day 8-bit computers with the same 
amount of memory. 
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1.1.1 The 68000 Registers 


Let's take a look at 68000 design. Figure 1.1-1 shows the 17 onboard 
32-bit registers, the program counter and the status register. 


The eight data registers can store and perform calculations, as well as the 
normal addressing tasks. Eight-bit systems use the accumulators for this, 
which limits the programmer to a total of 8 accumulators. Our 68000 data 
registers are quite flexibic, Uatz c2n be handled in 1-, 8-, 16- and 32- bit” 
sizes. Even four-bit operations are possible (within the limits of Binary 
Coded Decimal counting). When working with 32-bit data, all 32 bits can — 
be handled with a single operation. With 8- and 16-bit data, only the 8th or 
16th bit of the data register can be accesse<. 


The address registers aren't as flexible for data access as are the daia © 
registers. These registers are for addressing, not calculation. Processing 
data is possib:e on!v with word (16-bit) and longword (32-bit) operations. 
The address registers must be looked at as two distinct groups, the most 
versatile being the registers AO-A6. Registers A7 and A7' fulfill a special 
need. These registers are used as the stack pointer by the processor. Two 
stack pointers are needed to allow the 68000 to run in USER MODE and 
SUPERVISOR MODE. Register A7 declares whether the system is in 
USER or SUPERVISOR mode. Note that the two registers work "under" 
A7, but the zcatster contents are only available to the respective operating 
mode. We'll discuss these upuiuiins modes later. 


The program counter is also considered a 32-bit register. It is theoretically 
possible to handle an address range of over 4 gigabytes. But the address 
bits A24-A31 aren't used, which "limits" us to 16 megabytes. 


The 68000 status register comprises 16 bits, of which only 10 bits are used. 
This status register is divided into two halves: The lower eight bits (bits 0 
to 4 proper) is the "user byte". These bits, which act as flags most ot the 
time, show the results of arithmetical and comparative operations, and can 
be used for program branches hinging on those results. We'll look at the 
user byte in more detail later; for now, here is a brief list: 


BIT O = Carry flag BIT 1 = Overflow flag 
BIT 2 = Zero flag BIT 3 = Negative flag 
BIT 4 = eXtend flag 
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Figure 1.1-1 68000 Registers 
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Bits 8-10, 13 and 15 make up the status register's System byte. The 
remaining bits are unused. Bit 15 works as a trace bit, which lets you doa 
software controlled single-step execution of any program. Bit 13 is the 
Supervisor bit. When this bit is set, the 68000 is in supervisor mode. This 
is the normal operating mode; all commands are executed in this mode. In 
user mode, in which programs normally run, privileged instructions are 
inoperative. A special hardware design allows access into the other memory 
range while in user mode (e.g., important-system variables, I/O registers). 
The system byte of the status register can only be manipulated in supervisor 
mode; but there's a simple method of Switching between modes. 


Bits 8 and 10 show the interrupt mask, and run in connection with pins 
IPLO-IPL2. 


The 68000 has great potential for handling interrupts. Seven different 
interrupt priorities exist, the highest being the "non-maskable interrupt”; 
NMI. This interrupt recognizes when all three IPL pins simultaneously read 
low (0). If, however, all three IPL pins read high, there is no interrupt, and 
the system operates normally. The other six priorities can be masked by 
appropriate setting of the system byte of the status register. For example, if 
bit I2 of the interrupt mask is set, while IO and I1 are off, only levels 7, 6 
and 5 (000, 001 and 010) are recognized. All other combinations from 
IPLO-IPL2 are ignored by the processor. 
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1.1.2 Exceptions on the 68000 


We've spoken of interrupts as if the 68000 behaves like other 
microprocessors. Interrupts, according to Motorola nomenclature, are an 
external form of an exception (the machine can interrupt what it's doing, 
do something else, and return to the interrupted task if needed). The 68000 
distinguishes between normal operation and exception handling, rather than 
between user and supervisor mode. One such set of exceptions are the 
interrupts. Other things which cause exceptions are undefined opcodes, and 
word or longword access to a prohibited address. 


To make exception handling quicker and easier, the 68000 reserves the first 
1K of memory (1024 bytes, $000000-$0003FF). The exception table is 
located here. Exceptions are all coded as one of four bytes of a longword. 
Encountering an exception triggers the 68000, and the address of the 
corresponding table entry is output. 


A special exception occurs on reset, which requires 8 bytes (two 
longwords); the first longword contains the standard initial value of the 
supervisor stack pointer, while the second longword contains the address of 
the reset routine itself. See Chapter 3.3 for the design and layout of the 
exception table. 


1.1.3 The 68000 Connections 


The connections on the 68000 are divided into eight groups (see Figure 
1.1-3 on page 11). 


The first group combines data and address busses. The data bus consists of 
pins DQ-D15, and the address bus A1-A23. Address bit AO is not available 
to the 68000. Memory can be communicated with words rather than bytes 
(1 word=2 bytes=16 bits, as opposed to 1 byte=8 bits). Also, the 68000 
can access data located on odd addresses as well as even addresses. The 
signals will be dealt with later. 


It's important to remember in connection with this, that by word access to 
memory, the byte of the odd address is treated as the low byte, and the even 
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address is the high byte. Word access shouldn't stray from even addresses. 
That means that opcodes (whether all words or a single word) must always 
be located at even addresses. 


When the data and address bus are in "tri-state" condition, a third condition 
(in addition to high and low) exists, in which the pins offer high resistance, 
and thus are inactive on the bus. This 1s important in connection with Direct 
Memory Access (DMA). 


The second group of connections comprise the signals for asynchronous 
bus control. This group has five signals, which we'll now look at 
individually: 


1) R/W (READ/W RITE) 
The R/W signal is a familiar one to all microprocessors. This 
indicates to memory and peripherals whether the processor is writing 
to or reading data from the address on the bus. 


2) AS (ADDRESS STROBE) 
Every processor has a signal which it sends along the data lines 
signaling whether the address is ready to be used. On the 68000, this 
is known as the ADDRESS STROBE (low active). 


3) UDS (UPPER DATA 3sTROBE) 
4) LDS (LOWER DATA STROBE) 


If the 68000 could only process an entire memory word (two bytes) 
simultaneously, this signal wouldn't be necessary. However, for 
individual access to the low-byte and high-byte of a word, the 
processor must be able to distinguish between the two bytes. This is 
the task performed by UDS and LDS. When a word is accessed, 
both strobes are activated simultaneously (active=low). Accessing 
the data at an odd address activates the Lower Data Strobe only, while 
accessing data at an even address activates the Upper Data Strobe. 


Bit AO from the address bus is used in this case. After every access 
when the system must distinguish between three conditions (word, 
even byte, odd byte), AO determines how to complete the access. 


LDS and UDS are tri-state outputs. 
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5) DTACK 

The above signals (with the exception of UDS and LDS) are needed 
by an 8-bit processor. DTACK takes a different path, DTACK must 
be low for any write or read access to take place. If the signal is not 
low within a bus cycle, the address and data lines "freeze up" until 
DTACK turns low. This can also occur in a WAIT loop. This way, 
the processor can slow down memory and peripheral chips while 
performing other tasks. If no wait cycles are used on the ST, the 
processor moves "at full tilt". 


The third group of connections, the signals WMA, VPA and E are for 
synchronous bus control. A computer is more than memory and a 
microprocessor; interfaces to keyboard, screen, printer, etc. must be 
available for communication. In most cases, interfacing is handled by 
special ICs, but the 68000 has a huge selection of interface chips onboard. 
For hardware designers we'll take a little ttme explaining these synchronous 
bus signals. 


The signal E (also known as ®2 or phi 2) represents the reference count for 
peripherals. Users of 6800 and 6502 machines know this signal as the 
system counter. Whereas most peripheral chips have a maximum frequency 
of only 1 or 2 mHz, the 68000 has a working speed of 8 mHz, which can 
increased to 10 by the E signal. The frequency of E in the ST is 800 kHz. 
The E output is always active; it is not capable of a TRI- STATE condition. 


The signal VPA (Valid Peripheral Address) sends data over the 
synchronous bus, and delegates this transfer to specific sections of the chip. 
Without this signal, data transfer is performed by the asynchronous bus. 
VPA also plays a role in generating interrupts, as we'll soon see. 


VMA (Valid Memory Address) works in conjunction with the VPA to 
produce the CHIP-select signal for the synchronous bus. 


The fourth group of 68000 signals allows simple DMA operation in the 
68000 system. DMA (Direct Memory Access) directly accesses the DMA 
controllers, which control computer memory, and which is the fastest 
method of data transfer within a computer system. 


To execute the DMA, the processor must be in an inactive state. But for the 
processor to be signaled, it must be in a "sleep" state; the low BR signal 
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(Bus Request) accomplishes this. On recognizing the BR signal, the 
68000's read/write cycle ends, and the BG signal (Bus Grant) is activated. 
Now the DMA-requested chip waits until the signals AS, DTACK and 
(when possible) BGACK are rendered inactive. As soon as this occurs, the 
BGACK (Bus Grant Acknowledge) is activated by the requested chip , and 
takes over the bus. All essential signals on the processor are made high; in 
particular, the data, address and control busses are no longer influenced by 
the processor. The DMA controller can then place the desired address on 
the bus, and read or write data. When the DMA chip is finished with its 
task, the BGACK signal returns to its inactive state, and the processor again 
takes over the bus. 


The fifth group of signals on the 68000 control interrupt generation. The 
68000's "user's choice" interrupt concept is one of its most extraordinary 
performing qualities; you have 199 (!) interrupt vectors from which to 
choose. These interrupt vectors are divided into 7 non-auto-vectors and 192 
auto-vectors, plus 7 different priority lines. 


Interrupts are triggered by signals from the three lines IPLO to IPL2; these 
three lines give you eight possible combinations. The combination 
determines the priority of the interrupt. That is, if IPLO, IPL1 and IPL2 are 
all set high, then the lowest priority is set (‘no interrupt"). However, if all 
three lines are low, then highest priority takes over, to execute a 
non-maskable interrupt. All the combinations in between affect special bits 
in the 68000's status register; these, in turn, affect program control, 
regardless of whether or not a chosen interrupt is allowable. 


Wait -- what are auto-vectors and non-auto-vectors? What do these terms 
mean? 


If requesting an interrupt on IPLO-IPL2 while VPA is active (low), the 
desired code is directly converted from the IPL pins into a vector number. 
All seven interrupt codes on the IPL pins have their own vectors, though. 
_ The auto-vector concept automatically gives the vector number of the IPL 
interrupt code needed. 


When DTACK, instead of VPA, is active on an interrupt request, the 
interrupt is handled as a non-auto-vector. In this case, the vector number 
from the triggered chip is produced by DTACK on the 8 lowest bits of the 
data bus. Usually (though not important here), the vector number is placed 
into the user-vector range ($40--$FF). 
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The sixth set of connections are the three "function code" outputs FCO to 
FC2. These lines handle the status display of the processor. With the help 
of these lines, the 68000 can expand to four times 16 megabytes (64 
megabytes). This extension requires the MMU (Memory Management 
Unit). This MMU does more than handle memory expansion on the Sat 
also recognizes whether access is made to memory in user or supervisor 
mode. This information is conveyed to a memory range only accessible in 
supervisor mode. Also, the interrupt verification uses this information on 
the FC line. The figure below shows the possible combinations of 
functions. 


Supervisor data access 
Supervisor program 
Interrupt verification 


Figure 1.1-3 
BG2:: PC bos PEO ss Sia eus 
O O 0 unused 
O 0 1 User-mode data access 
0 af 0 User-mode program 
0 1 4 unused 
1 0 0 unused 
1 0 is 
1 5 0 
1 i 1 


The seventh group contains system control signals. This group applies to 
the input CLK and BERR, as well as the bidirectional lines RESET and 
HALT. 


The input CLK will generate the working frequency of the processor. The 
68000 can operate at different speeds; but the operating frequency must be 
specified (4, 6, 8, 10, or even 12.5 mHz). The ST has 8 mHz built in, 
while the minimum operating frequency is 2 mHz. The ST's 8 mHz was 
chosen as a "middle of the road" frequency to avoid losing data at higher 
frequencies. 


The RESET line is necessary to check for system power-up. The 68000's 
data page distinguishes between two different reset conditions. On 
power-up, RESET and HALT are switched low for at least 100 
milliseconds, to set up a proper initialization. Every other initialization 
requires a low impulse of at least 4 "beats" on the 68K. 


Here is what RESET does in detail. The system byte of the status register is 
loaded with the value $27. Once the processor is brought into supervisor 
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status, the Trace flag in the status register is cleared, and the interrupt level 
is set to 7 (lowest priority, all lines allowable). Additionally, the supervisor 
stack pointer and program counter are loaded with the contents of the first 8 
bytes of memory, whereby the value of the program counter is set to the 
beginning of the reset routine. 


However, since the RESET line is bi-directional, the processor can also 
have RESET under program control during the time the line is low. The 
RESET instruction serves this purpose, when the connection is low for 124 
“beats". It's possible to re-initialize the peripheral ICs at any time, without 
resetting the computer itself. RESET time puts the 68000 into a NOP state 
-- areset is unstoppable once it occurs. 


The HALT pin is important to the RESET line's existence (as we mentioned 
above), in order to initialize things properly. This pin has still more 
functions: when the pin is low while RESET is high, the processor goes 
into a halt state. This state causes the DMA pin to set the processor into the 
tri-state condition. The HALT condition ends when HALT is high again. 
This signal can be used in the design of single-step control. 


HALT is also bi-directional. When the processor signals this line to become 
low, it means that a major error has occurred (e.g., doubled bus and 
address errors). 


A low state on the BERR pin will call up exception handling, which runs 
basically like an external interrupt. In an orderly system, every access to the 
asynchronous bus quits with the DTACK signal. When DTACK is - 
outputting, however, the hardware can produce a BERR, which informs the 
processor of any errors found. A further use for BERR is in connection 
with the MMU, to test for proper memory access of a specific range; this 
access 1s signaled by the FC pins. If protected memory is tried for in user 
mode, a BERR will turn up. 


When both BERR and HALT are low, the processor will "re-execute"” the 
instruction at which it stopped. If it doesn't run properly on the second 
go-round", then it's called a doubled bus error, and the processor halts. 


The eighth group of connections are for voltage and ground. 
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1.2 The Custom Chips 


The Atari ST has four specially developed ICs. These chips (GLUE, 
MMU, DMA and SHIFTER) play a major role in the low price of the ST, 
since each chip performs several hundred overlapping functions. The first 
prototype of the ST was 5 X 50 X 30 cm. in size, mostly to handle all those 
TTL ICs. Once multiple functions could be crammed into four ICs, the ST 
became a saleable item. Then again, the present ST hasn't quite reached the 
ultimate goal -- it still has eight TTLs. 


~ Naturally, since these chips were specifically designed by Atari for the ST, 
they haven't been publishing any spec sheets. Even without any data specs, 
we can give you quite a bit of information on the workings of the ICs. 


An interesting fact about these [Cs is that they're designed to work in 
concert with one another. For example, the DMA chip can't operate alone. 
It hasn't an address counter, and 1s incapable of addressing memory on its 
own (functions which are taken care of by the MMU). It's the same with 
SHIFTER -- it controls video screen and color, but it can't address video 
RAM. Again, MMU handles the addressing. 


The system programmer can easily figure out which IC has which register. 
It is only essential to be able to recognize the address of the register, and 
how to control it. We're going to spend some time in this chapter exploring 
_ the pins of the individual ICs. 


The most important IC of the "foursome" is GLUE. Its title speaks for the 
function -- a glue or paste. This IC, with its 68 pins, literally holds the 
entire system together, including decoding the address range and working 
the peripheral ICs. 


Furthermore, the DMA handshake signals BR, BG and BGACK are 
produced/output by GLUE. The time point for DMA request is dictated by 
GLUE by the signal from the DMA controller. GLUE also has a BG (Bus 
Grant) input, as well as a BGO (Bus Grant Out). 


The interrupt signal is produced by GLUE; in the ST, only IPL1 and IPL2 


are used for this. Without other hardware, you can't use NMI (interrupt 
level 7). The pins MFPINT and IACK are used for interrupt control. 
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Figure 1.2-1 GLUE 
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The function code pins are guided by GLUE, where memory access tasks 
are performed (range testing and access authorization). Needless to say, the 
BERR signal is also handled by this chip. WPA is particularly important to 
the peripheral ICs and the appropriate select signals. 


GLUE generates a timing frequency of 8 mHz. Frequencies between 2 
mHz (sound chip's operating frequency) and 500 kHz (timing for keyboard 
and MIDI interface) can be produced. 


HSYNC, VSYNC, BLANK and DE (Display Enable) are generated by 
GLUE for monitor operation. The synchronous timing can be switched on 
and off, and external sync-signals sent to the monitor. This will allow you 
~ to synchronize the ST's screen with a video camera. 


The MMU also has a total of 68 pins. This IC performs three vital tasks. 
The most important task is coupling the multiplexed address bus of dynamic 
RAM with the processor's bus (handled by address lines Al to A21). This 
gives us an address range totaling 4 megabytes. Dynamic RAM is 
controlled by RASO, RAS1, CASOL, CASOH, CAS1L and CASIH, as 
well as the multiplexed address bus on the MMU. DTACK, R/W, AS, LDS 
and UDS are also controlled by MMU. 


We've already mentioned another important function of the MMU: it works 
with the SHIFTER to produce the video signal (the screen information is 
addressed in RAM, and SHIFTER conveys the information). Counters are 
incorporated in the MMU for this; a starting value is loaded, and within 500 
- nanoseconds, a word is addressed in memory and the information is sent 
over DCYC. The starting value of the video counter (and the screen 
memory position) can be shifted in 256-byte increments. 


Another integrated counter in MMU, as mentioned earlier, is for addressing 
memory using the DMA. This counter begins with every DMA access (disk 
or hard disk), loading the address of the data being transferred. Every 
transfer automatically increments the counter. 


The SHIFTER converts the information in video RAM into impulses 


readable on a monitor. Whether the ST is in 640 X 200 or 320 X 200 
resolution, SHIFTER is involved. 
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Figure 1.2-2 MMU 


UDS* 
WDAT* 
DMA 

WE * 
CAS1LHIGH 
CAS1LLOW 
8MHZ out 
4MHZ out 
RAS1 
LDS* 
A21 

A20 

A19 

A18 

A17 

Al16 

Vcc 


26 
25 
24 
pe 
ce 
21 
20 
19 
18 
Kate 4 
16 
A ios 
14 
A 
12 
a ge 
10 


GNpD* 27 © i 9 LATCH 
cmMpcs 28 © we 8 RASO 
peycs 29 % S 7 CASOLOW 
RDAT* 30 © Le 6 CASOHIGH 
DEV* 31 © ee) 5 16MHZ IN 
AS cv @ is 4 D7 
RAM* 33 © i 3 D6 
R/we 34 © mD 2 D5 
A15 35: % 1 D4 
Al4 36 © Di 68 4ip3 
A13 37 ES) Sin67 -p2 
Al2 38 U Eo" 66? D2 
All 39 U Pet. 652 D0 
A10 40 4 64 MAD 9 
AQ 41.4 S 63 MAD 8 
A8 42% DO) 2620 MAD <7 
AT 43 [> 61 GND 
J JUUUUU UU UUU U0 Uh 
TONUOPAHOUNGYNOR ADO 
STV VFVV YIN DYN pnNNnNnNnNnNY 


16 


Abacus Software Atari ST Internals 


Figure 1.2-3 SHIFTER 
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The information from RAM is transferred to SHIFTER on the signal 
LOAD. A resolution of 640 X 400 points sends the video signal over the 
MONO connector. Since color is impossible in that mode, the RGB 
connection is rendered inactive. The other two resolutions set MONO 
output to inactive, since all screen information is being sent out the RGB 
connection in those cases. 


The third color connection works together with external equipment as a 
digital/analog converter. Individual colors are sent out over different pins, 
to give us color on our monitor. Pins R1- RS5 on the address bus make up 
the "palette registers". These registers contain the color values, which are 
placed in individual bit patterns. The 16 palette registers hold a total of 16 
colors for 320 X 200 mode. Note, however, that since these are based o~ 
the "primary" colors red, green and blue, these colors can be adjusted in o 
steps of brightness, bringing the color total to 512. 


The DMA controller is like SHIFTER, only in a 40-pin housing; it is used 
to oversee the floppy disk controller, the hard disk, and any other 
peripherals that are likely to appear. 


The speed of data transfer using the floppy disk drive offers no problems to 
the processor. It's different with hard disks; data moves at such high speed 
that the 68000 has to send a "pause" over the 8 mHz frequency. This pace 
is made possible by the DMA. 


The DMA is joined to the processor's data bus to help transfer data. Two 
registers within the machine act as a bi-directional buffer for data through 
the DMA port; we'll discuss these registers later. One interesting poin. 
The processor's 16-bit data bus is reduced to 8 bits for floppy/hard disk 
work. Data transfer automatically transfers two bytes per word. 


The signals CA1, CA2, CR/W, FDCS and FDRQ manage the floppy disk 
controller. CA1 and CA2 are signals which the floppy disk controller 
(FDC) uses to select registers. CR/W determine the direction of data 
transfer from/to the FDC, and other peripherals connected to the DMA port. 


The RDY signal communicated with GLUE (DMA-request) and MMU 
(address counter). This signal tells the DMA to transfer a word. 


As you can see, these ICs work in close harmony with one another, and 
each would be almost useless on its own. 
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1.3 The WD 1772 Floppy Disk Controller 


Although the 1772 from Western Digital has only 28 pins, this chip contains 
a complete floppy disk controller (FDC) with capabilities matching 40-pin 
controllers. This IC is software-compatible with the 1790/2790 series. 
Here are some of the 1772's features: 


Simple 5-volt current 

Built-in data separator 

Built-in copy compensation logic 
Single and double density 
Built-in motor controls 


Although the user has his/her choice of disk format, e.g. sector length, 
number of sectors per track and number of tracks per diskette, the "normal" 
format 1s the optimum one for data transfer. So, Apple or Commodore 
diskettes can't be used. 


Before going on to details of the FDC, let's take a moment to look at the 28 
pins of this IC. 


1.3.1 1772 Pins 


These pins can be placed in three categories. The first group consists of the 
power connections. 


V Ce: 

+5 volts current. 
GND: 

Ground connection. 
MR: 


Master reset. FDC reinitializes when this is low. 


The second set are processor interface pins. These pins carry data between 
the processor and the FDC. 
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Figure 1.3-1 FDC 1772 
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D0-D7: 


CS: 


R/W: 


A0,AL: 


DRQ: 


CLK: 


Eight-bit bi-directional bus; data, commands and status 
information go between FDC and system. 


FDC can only access registers when this line is low. 


Read/Write. This pin states data direction. HIGH= read by FDC, 
LOW=write from FDC. 


These bits determine which register is accessed (in conjunctior— 
with R/W). The 1772 has a total of five registers which can both 
read and write to some degree. Other registers can only read OR 
write. Here is a table to show how the manufacturer designed 
them: 


Al A R/W=1 R/W= 

O 0 Status Reg. Command Reg. 
0 1 Track Reg. Track Reg. 

1 Q Sector Reg. sector Reg. 
1 vi Data Reg. Data Reg. 


Data Request. When this output is high, either the data register is 
full (from reading), and must be "dumped", or the data register is _ 
empty (writing), and can be refilled. This connection aids the 
DMA operation of the FDC. 


Clock. The clock signal counts only to the processor bus. An 
input frequency of 8 mHz must be on, for the FDC's internal 
timing to work. 


The third group of signals make up the floppy interface. 


STEP: 


DIRC: 


Sends an impulse for every step of the head motor. 


Direction. This connection decides the direction of the head; high 
moves the head towards center of the diskette. 
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RD: 
Read Data. Reads data from the diskette. This information 
contains both timing and data impulses -- it is sent to the internal 
data separator for division. 

MO: 
Motor On. Controls the disk drive motor, which is automatically 
started during read/write/whatever operations. 

WG: 
Write Gate. WG will be low before writing to diskette. Write 
logic would be impossible without this line. 

~~ WD: 

Write Data. Sends serial data flow as data and timing impulses. 

TROO: 
Track 00. This moves read/write head to track 00. TROO would 
be low in this case. 

IP: 
Index Pulse. The index pulses mark the physical beginnings of 
every track on a diskette. When formatting a disk, the FDC 
marks the start of each track before formatting the disk. 

WPRT: 
Write Protect. If the diskette is write-protected, this input wil 

_ react. | 
DDEN: 


Double Density Enable. This signal is confined to floppy disk 
control; it allows you to switch between single-density and 
double-density formats. 
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1.3.2 1772 Registers 


CR (Command Register): 
Commands are written in this 8-bit register. Commands should 
only be written in CR when no other command is under 
execution. Although the FDC only understands 11 commands, 
we actually have a large number of possibilities for these 
commands (we'll talk about those later). 


STR (Status Register): 
Gives different conditions of the FDC, coded into individual bits. - 
Command writing depends on the meaning of each bit. The 
Status register can only be read. 


TR (Track Register): 
Contains the current position of the read/write head. Every 
movement of the head raises or lowers the value of TR 
appropriately. Some commands will read the contents of TR, 
along with information read from the disk. The result affects the 
Status Register. TR can be read/written. 


SR (Sector Register): 
SR contains the number of sectors desired from read/write 
operations. Like TR, it can be used for either operation. 


DR (Data Register): 
DR is used for writing data to/ reading data from diskette. 


24 


Abacus Software Atari ST Internals 


1.3.3 Programming the FDC 


Programming this chip 1s no big deal for a system programmer. Direct (and 
in most cases, unnecessary) programming 1s made somewhat harder AND 
drastically simpler by the DMA chip. The 11 FDC commands are divided 
into four types. 


Type 


PS WW WN DF ee 


Function 

Restore, look for track O00 

Seek, look for a track 

Step, a track in previous direction 

Step In, move head one track in (toward disk hub) 
Step Out, move head one track out (toward edge of disk) 
Read Sector 

Write Sector 

Read Address, read ID 

Read Track, read entire track 

Write Track, write entire track (format) 

Force Interrupt 


Type 1 Commands 


These commands position the read/write head. The bit patterns of these five 


7: commands look like this: 


Bir 
toy Oe a Be ee ee i) 
Restore Oe 0) “Ol wi. ver RRO 
Seek OA - O02 eG -h ei SHV RIE RO 
Step 0.2202) 2s Bis HAA DIRDSRO 
Step In O21: (ent Maye. “VsrRi eR 
Step: Oat a0 wlee bus Ue oH Ove ARIE RO 
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All five commands have several variable bits; bits RO and R1 give the time 
between two step impulses. The possible combinations are: 


Rl RO STEP RATE 

0 O 2 milliseconds 
O 1 3 milliseconds 
4 QO .chi milliseconds 
a 1 6 milliseconds 


These bits must be set by the command bytes to the disk drive. The V-bit is 
the so-called "verify flag". When set, the drive performs an automatic 
verify after every head movement. The H-bit contains the spin-up 
sequence. The system delays disk access until the disk motor has reached ~- 
300 rpm. If the H-bit is cleared, the FDC checks for activation of the 
motor-on pins. When the motor 1s off, this pin will be set high (motor on), 
and the FDC waits for 6 index impulses before executing the command. If 
the motor 1s already running, then there will be no waiting time. 


The three different step commands have bit 4 designated a U- bit. Every 
step and change of the head appears here. 
T 2 mman 


These commands deal with reading and writing sectors. They also have 
individual bits with special meanings. 


Bk 7] 6 5 4 3 a - O 
Read Sector 1 0 0 M H E O QO 
Write Sector 1 0 1 M H E Pp AQ 


The H-bit is the previously described start-up bit. When the E-bit is set, the 
FDC waits 30 milliseconds before starting the command. This delay is 
important for some disk drives, since it takes time for the head to change 
tracks. When the E-bit reads null, the command will run immediately. 


The M-bit determines whether one or several sectors are read one after 
another. On a null reading, only one sector will be read from/written to. 
Multi-sector reading sets the bit, and the FDC increments the counter at each 
new sector read. 


Bits 0 and 1 must be cleared for sector reading. Writing has its own special 
meaning: the AO bit conveys to bit 0 whether a cleared or normal data 
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address mark is to be written. Most operating systems don't use this option 
(a normal data address mark is written). 


The P-bit (bit 1) dictates whether pre-compensation for writing data is 
turned on or off. Pre-compensation is normally set on; it supplies a higher 
degree of protection to the inner tracks of a diskette. 


Type 3 Commands 


Read Address gives program information about the next ID field on the 
diskette. This ID field describes track, sector, disk side and sector length. 
Read Track gives all bytes written to a formatted diskette, and the data 
“between sectors". Write Track formats a track for data storage. Here are 
the bit patterns for these commands: 


BIT yO ne Ds. 
Read Address 1 EO AD 2 BEE OB 
Read Track aS: le 5 ad 1 
Write Track dee de ks Ay Bee 


The H- and E-bits also belong to the Type 2 command set (spin-up and 
head-settle time). The P-bit has the same function as in writing sectors. 


Type 4 Commands 


There's only one command in this set: Force Interrupt. This command can 
work with individual bits during another FDC command. When this 
command comes into play, whatever command was currently running is 
ended. 


BIT dh” sO TO. A 38 eae ae 
fOrce,Inverrupe 1° “i f'O-*- “ma 465-81 


Bits I0-I3 present the conditions under which the interrupt is pressed. IO 
and Il have no meaning to the 1772, and remain low. If I2 is set, an 
interrupt will be produced with every index impulse. This allows for 
Software controlled disk rotation. If I3 is set, an interrupt is forced 
immediately, and the currently-running command ends. When all bits are 
null, the command ends without interruption. 
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1.4 The MFP 68901 


MFP is the abbreviation for Multi-Function Peripheral. This name is no 
exaggeration; wait until you see what it can do! Here's a brief list of the 
most noteworthy features: 


8-bit parallel port 

Data direction of every port bit is individually programmable 
Port bits usable as interrupt input 

16 possible interrupt sources 

Four universal timers 

Built-in serial interface 


1.4.1 The 68901 Connections 


The 48 pins of the MFP are set apart in function groups. The first function 
group is the power connection set: 


GND, Vcc, CLK: 
Vcc and GND carry voltage to and from the MFP. CLK 1s the 
clock input; this clock signal must not interfere with the system 
timer of the processor. The ST's MFP operates at a frequency of 
4 mHz. 


Communication with the data bus of the processor is maintained with 
DO0-D7, DTACK, RS1-RS5 and RESET. 


DO0-D7: 
These bi-directional pins normally work with the 8 lowest data 
bits of the 68000. It is also possible to connect with D8 through 
D15, but it's impossible to produce non-auto interrupts. Thus, 
interrupt vectors travel along the low order 8 data bits. 


Abacus Software Atari ST Internals 


eee 
Figure 1.4-1 MFP 68901 
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CS (Chip Select): 
This line is necessary to communication with the MFP. CS is 
active when low. 


DS (Data Strobe): 
This pin works with either LDS or UDS on the processor. 
Depending on the signal, MFP will operate either the lower or 
upper half of the data bus. 


DTACK (Data Transfer ACKnoledge): 
This signal shows the status of the bus cycle of the processor 
(read or write). 


RS1-RS5 (Register Select): 
These pins normally connect with to the bottom five address lines 
of the processor, and serve to choose from the 24 internal 
registers. 


RESET: 
If this pin is low for at least 2 microseconds, the MFP initializes. 
This occurs on power-up and a system reset. 


The next group of signals cover interrupt connections (IRQ, IACK, IEI and 
TE), 


IRQ (Interrupt ReQuest): 
IRQ will be low when an interrupt is triggered in the MFP. This 
informs the processor of interrupts. 


IACK (Interrupt ACKnowledge): 
On an interrupt (IRQ and IEI), the MFP sends a low signal over 
IACK and DS on the data lines. Since 16 different interrupt 
sources are available, this makes handling interrupts much 
simpler. 


IEI, IEO (Interrupt Enable In/ Out): 
These two lines permit daisy-chaining of several MFPs, and 
determine MFP priority by their positioning in this chain. IEI 
would work through the MFP with the highest priority. IEO of 
the second MFP would remain unswitched. On an interrupt, a 
signal is sent over IACK, and the first MFP in the chain will 
acknowledge with a high IEO. 
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Next, we'll look at the eight I/O lines. 


IO0-7 (Input/Output): 
These pins use one or all normal I/O lines. The data direction of 
each port bit is set up in a data direction register of its own. In 
addition, though, every port bit can be programmed to be an 
interrupt input. 


The timer pins make up yet another group of connections: 


XTAL1,2 (Timer Clock Crystal): 
A quartz crystal can be connected to these lines to deliver a 
working frequency for the four timers. 


TAI,TBI (Timer Input): 
Timers A and B can not only be used as real counters differently 
from timers C and D with the frequency from XTALI and 2, but 
can also be set up for event counting and impulse width 
measurement. In both these cases, an external signal (Timer 
Input) must be used. 


TAO,TBO,TCO,TDO (Timer Output): 
Every timer can send out its status on each peg (from 01 to 00). 
Each impulse is equal to 01. 


The second-to-last set of signals are the connections to the universal serial 
interface. The built-in full duplex of the MFP can be run synchronously or 
asynchronously, and in different sending and receiving baud rates. 


SI (Serial Input): 
An incoming bit current will go up the SI input. 


SO (Serial Output): 
Outgoing bit voltage (reverse of SI). 


RC (Receiver Clock): 
Transfer speed of incoming data is determined by the frequency 
of this input; the source of this signal can, for example, be one of 
the four timers. 


TC (Transmitter Clock): 


Similar to RC, but for adjusting the baud-rate of data being 
transmitted. 
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The final group of signals aren't used in the Atari ST. They are necessary 
when the serial interface is operated by the DMA. 


RR (Receiver Ready): | 
This pin gives the status of the receiving data registers. If a 
character is completely received, this pin sends current. 


TR (Transmitter Ready): 
This line performs a similar function for the sender section of the 
serial interface. Low tells the DMA controller that a new 
character in the MFP must be sent. 


1.4.2 The MFP Registers 


As we've already mentioned, the 68901 has a total of 24 different registers. 
This large number, together with the logical arrangement, makes 
programming the MFP much easier. 


Reg 1 GPIP, General Purpose I/O Interrupt Port 
This is the data register for the 8-bit ports, where data from the 
port bits is sent and read. 


Reg 2 AER, Active Edge Register 
When port bits are used for input, this register dictates whether 
the interrupt will be a low-high- or high-low conversion. Zero is 
used in the high-low change, one for low-high. 


Reg 3 DDR, Data Direction Register 
We've already said that the data direction of individual port bits 
can be fixed by the user. When a DDR bit equals 0, the 
corresponding pin becomes an input, and 1 makes it an output. 
Port bit positions are influenced by AER and DDR bits. 
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Reg 4,5 IERA,IERB, Interrupt Enable Register 

Every interrupt source of the MFP can be separately switched on 
and off. With a total of 16 sources, two 8-bit registers are 
needed to control them. If a 1 has been written to IERA or 
IERB, the corresponding channel is enabled (turned on). 
Conversely, a zero disables the channel. If it comes upon a 
closed channel caused by an interrupt, the MFP will completely 
ignore it. The following table shows which bit is coordinated 
with which interrupt occurrence: 


IERA 

Bit: 7211/0 portisbit.7- (highest«priority) 
Bat 6 %2I/0 ports bik °6 

Bit... 5:t:Timer A 

Bit 4: Receive buffer full 

Bit 3: Receive error 

Bit 2: Sender buffer empty 

Bit 1: Sender error 

Bit 02 Tamer 2 

ITERB 

Baty i+ 2E/O pert: bits 

Bit (6; 2/0; port bat.4 

Bit) 53. TimerC 

Bit 4: Timer D 

Bac: oF 1/0 Port -pit. 3 

Bit 2t.-t/O pore “bit. 2 

BLe jb-isck/Oepont' bit: 1 

Bit 0: I/O port bit 0, lowest priority 


This arrangement applies to the IP-, IM- and IS-registers 
discussed below. 


Reg 6,7 IPRA,IPRB, Interrupt Pending Register 
When an interrupt occurs on an open channel, the appropriate bit 
in the Interrupt Pending Register is set to 1. When working with 
a system that allows vector creation, this bit will be cleared when 
the MFP puts the vector number on the data bus. If this isn't 
possible, the IPR must be cleared using software. To clear a bit, 
a byte in the MFP will show the location of the specific bit. 


The bit arrangement of the IPR bit arrangement is shown in the 
table for registers 4 and 5 (see above). 
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Reg 8,9 


Reg 10,1 


ISRA,ISRB,Interrupt In-Service Register 

The function of these registers is somewhat complicated, and 
depends upon bit 3 of register 12. This bit is an S-bit, which 
determines whether the 68901 is working in "Software End-of- 
Interrupt” mode (SEI) or in "Automatic End-of-Interrupt" mode 
(AEI). AEI mode clears the IPR (Interrupt Pending Bit), when 
the processor gets the vector number from the MFP during an 
IACK cycle. The appropriate In-Service bit is cleared at the same 
time. Now a new interrupt can occur, even when the previous 
interrupt hasn't finished its work. 


SEI mode sets the corresponding ISR-bit when the vector 
number of the interrupt is requested by the processor. At the 
interrupt routine’s end, the bit designated within the MFP must 
be cleared. As long as the Interrupt In-Service bit is set, all 
interrupts of lower priority are masked out by the MFP. Once the 
Pending-bit of the active channel is cleared, the same sort of 
interrupt can occur a second time, and interrupts of lesser priority 
can occur as well. 


1 IMRA,IMRB Interrupt Mask Register 

Individual interrupt sources switched on by IER can be masked 
with the help of this register. That means that the interrupt 1s 
recognized from within and is signaled in the IPR, even if the 
IRQ line remains high. 


Reg 12 VR Vector Register 


In the cases of interrupts, the 68901 can generate a vector number 
corresponding to the interrupt source requested by the processor 
during an Interrupt Acknowledge Cycle. All 16 interrupt 
channels have their own vectors, with their priorities coded into 
the bottom four bits of the vector number (the upper four bits of 
the vector are copied from the vector register). These bits must 
be set into VR, therefore. 


Bit 3 of VR is the previously mentioned S-bit. If this bit is set 
(like in the ST), then the MFP operates in "Software End-of- 
Interrupt” mode; a cleared bit puts the system into "Automatic 
End-of-Interrupt” mode. 
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Reg 13,14 TACR,TBCR Timer A/B Control Register 

Before proceeding with these registers, we should talk for a 
moment about the timer. Timers A and B are both identical. 
Every timer consists of a data register, a programmable feature 
and an 8-bit count-down counter. Contents of the counters will 
decrease by one every impulse. When the counter stands at 01, 
the next impulse changes the corresponding timer to the output of 
its pins. At the same time, the value of the timer data register is 
loaded into the timer. If this channel is set by the IER bit, the 
interrupt will be requested. The source of the timer beats will 
usually be those quartz frequencies from XTALI1 and 2. This 
operating mode is called delay mode, and is available to timers C 
and D. 


Timers A and B can also be fed external impulses using timer 
inputs TAI and TBI (in event count mode). The maximum 
frequency on timer inputs should not surpass 1/4 of the MFP's 
operating frequency (that is, 1 mHz). 


Another peculiarity of this operating mode is the fact that the 
timer inputs for the interrupts are I/O pins 13 and 14. By 
programming the corresponding bits in the AER, a pin-jump can 
be used by the timer inputs to request an interrupt. TAI is joined 
with pin 13, TBI by pin 14. Pins 13 and 14 can also be used as 
I/O lines without interrupt capability. 


Timers A and B have yet a third operating mode (pulse-length 
measurement). This is similar to Delay Mode, with the difference 
that the timer can be turned on and off with TAI and TBI. Also, 
when pins 13 and 14 are used, the AER-bits can determine 
whether the timer inputs are high or low. If, say, AER-bit 4 is 
set, the counter works when TAI is high. When TAI changes to 
low, an interrupt is created. 


Now we come to TACR and TBCR. Both registers only use the 


fifth through eighth bits. Bits 0 to 3 determine the operating 
mode of each timer: 
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BIT. 3 


PRPRPRPRPRRFPRPRPODDOCOCCO 


NO 


are Po. eee CO CD Ce) ee ae ee 2 ee 


bo 


oe 


Function 


Timer 
Delay 
Delay 
Delay 
Delay 
Delay 
Delay 
Delay 
Delay 


SCOD, 
mode, 
mode, 
mode, 
mode, 
mode, 
mode, 
mode, 
mode, 


divides 
divides 
divides 
divides 
divides 
divides 
divides 
divides 
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no function executed 
subdivider 
subdivider 
subdivider 
subdivider 
subdivider 
subdivider 
subdivider 
subdivider 


by 
by 
by 
by 
by 
by 
by 
by 


10 
16 
16 
20 
64 
100 
200 


Count Mode 
extension 
extension 
extension 
extension 
extension 
extension 
extension 


Event 
Pulse 
Pulse 
Pulse 
Pulse 


by 4 

by 10 
by 16 
py 50 
by 64 
by 100 
by 200 


divides 
divides 
divides 
divides 
divides 
divides 
divides 


mode, subdivider 
mode, subdivider 
mode, subdivider 
mode, subdivider 
mode, subdivider 
mode, subdivider 
mode, subdivider 


Pulse 
Pulse 
Pulse 


PRPOOFRPRPOOFRPRPOORPRFROO 
FPOrRPOFPOFPFOrFPORFPOFRFROFRO 


Bit 4 of the Timer Control Register has a particular function. 
This bit can produce a low reading for the timer being used with 
it at any time. However, it will immediately go high when the 
timer runs. 


Reg 15 TCDCR Timers C and D Control Register 


Bit 
Bit 


ae Pe ee Co oo oO Co Oye 


Timers C and D are available only in delay mode; thus, one byte 
controls both timers. The control information is programmed 
into the lower three bits of the nibbles (four- bit halves). Bits O 
and 2 arrange Timer D, Timer C 1s influenced by bits 4 and 6. 
Bits 3 and 7 in this register have no function. 


Function -: Timer .D 
Function: —- Timer G 
Timer Stop 
Delay Mode, 
Delay Mode, 
Delay Mode, 
Delay Mode, 
Delay Mode, 
Delay Mode, 
Delay Mode, 


division 
division 
division 
division 
division 
division 
division 


FPROOrRPRPOOUEH 
FOrFPOrPOFrRFORO 
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Reg 16-19 TADR,TBDR,TCDR,TDDR Timer Data Registers 
The four Timer Data Registers are loaded with a value from the 
counter. When a condition of 01 1s reached, an impulse occurs. 
A continuous countdown will stem from this value. 


Reg 20 SCR Synchronous Character Register 
A value will be written to this register by synchronous data 
transfer, so that the receiver of the data will be alerted. When 
synchronous mode is chosen, all characters received will be 
stored in the SCR, after first being put into the receive buffer. 


Reg 21 UCR,USART Control Register 
USART 1s short for Universal Synchronous/Asynchronous 
Receiver/Transmitter. The UCR allows you to set all the 
operating parameters for the interfaces. Parameters can also be 
coded in with the timers. 


Bit: 0 : unused 
Bat ek > O=Odd parity 
1=Even parity 


Bat. 2 : O=No parity (bit 1 is ignored) 
l=Paraity according to bit -1 


Buits..3,747 <: These: bis :coptrolthe - numberof 
start- and stopbits and the 
format desired. 
Start Stop: Format 

O OQ Synchronous 

1 1 Asynchronous 

1 1,5 Asynchronous 

1 Z Asynchronous 


Bit 


pe sO © 
Pe Aare Ct) 


Bits..5,6.. %-). These. bits give ‘the 
"wordlength" of the data bits 
to be transferred. 

Word length 

8 bits 

I bats 

6: bats 

obits 


Bits 


ro) = OCA 


a7 
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But. 7 > O=Frequency from TC and RC 
directly used as transfer 
frequency (used only for 
Synchronous transfer) 
l=Frequency in TC and RC 
internally divided by 16. 


Reg 22 RSR Receiver Status Register 
The RSR gives information concerning the conditions of all 
receivers. Again, the different conditions are coded into 
individual bits. 


Bit O Receiver Enable Bit 
When this bit is cleared, receipt is immediately turned off. 
All flags in RSR are automatically cleared. A set bit means 
that the receiver is behaving normally. 


Bit 1 Synchronous Strip Enable 
This bit allows synchronous data transfer to determine 
whether or not a character in the SCR is identical to a 
character in the receive buffer. 


Bit 2 Match/Character in Progress 
When in synchronous transfer format, this bit signals that a 
character identical with the SCR byte would be received. 
In asynchronous mode, this bit is set as soon as the startbit 
is recognized. A stopbit automatically clears this bit. 


Bit 3 Found - Search/Break Detected 

This bit is set in synchronous transfer format, when a 
character received coincides with one stored in the SCR. 
This condition can be treated as an interrupt over the 
receiver's error channel. Asynchronous mode will cause 
the bit to set when a BREAK is received. The break 
condition is fulfilled when only zeroes are received 
following a startbit. To distinguish between a BREAK 
from a "real" null, this line should be low. 


Bit 4 Frame Error 


A frame error occurs when a byte received is not a null, but 
the stopbit of the byte IS a null. 
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Bit 5 Parity Error 
The condition of this bit gives information as to whether 
parity on the last received character was correct. If the 
parity test is off, the PE bit is untouched. 


Bit 6 Overrun Error 
This bit will be set when a complete character is in the 
receiver floating range but not read into the receive buffer. 
This error can be operated as an interrupt. 


Bit 7 Buffer Full 
This bit is set when a character is transferred from the 
floating register to the receive buffer. As soon as the 
processor reads the byte, the bit is cleared. 


Reg 23 TSR Transmitter Status Register 
Whereas the RSR sends receiver information, the TSR handles 
transmission information. 


Bit O Transmitter Enable 
The sending section is completely shut off when this bit is 
cleared. At the same time the End-bit is cleared and the UE- 
bit is set (see below). The output to the receiver is set in 
the corresponding H- and L-bits. 


Bits 1,2 High- and Low-bit 

These bits let the programmer decide which mode of output 
the switched-off transmitter will take on. If both bits are 
cleared,the output is high. High-bit only will create high 
output; low-bit, low output. Both bits on will switch on 
loop-back-mode. This state loops the output from the 
transmitter with receiver input. The output itself is on the 
high-pin. 


Bit 3 Break 
The break-bit has no function in synchronous data transfer. 
In asynchronous mode, though, a break condition 1s sent 
when the bit is set. 
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Bit 4 End of Transmission 
If the sender is switched off during running transmission, 
the end-bit will be set as soon as the current character has 
been sent in its entirety. When no character is sent, the bit 
is immediately set. 


Bit 5 Auto Turnaround 
When this bit is set, the receiver is automatically switched 
on when the transmitter is off, and a character will 
eventually be sent. 


Bit 6 Underrun Error 
This bit is switched on when a character in the sender 
floating register will be sent, before a new character is 
written into the send buffer. 


Bit 7 Buffer Empty 
This bit will be set when a character from the send buffer 
will be transferred to the floating register. The bit is 
cleared when new data is written to the send buffer. 


Reg 24 UDR, USART Data Register 
Send/receive data is sent over this register. Writing sends data in 
the send buffer, reading gives you the contents of the receive 
buffer. 
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1.5 The 6850 ACIAs 


ACIA is short for "Asynchronous Communications Interface Adapter”. 
This 24-pin IC has all the components necessary for operating a serial 
interface, as well as error-recognizing and data-formatting capabilities. 
Originally for 6800-based computers, this chip can be easily tailored for 
6502 and 68000 systems. The ST has two of these chips. One of them 
communicates with the keyboard, mouse, joystick ports, and runs the 
clock. Keyboard data travels over a serial interface to the 68000 chip. The 
second ACIA is used for operating the MIDI interface. 


Parameter changes in the keyboard ACIA are not recommended: The 
connection between keyboard and ST can be easily disrupted. The MIDI 
interface is another story, though -- we can create all sorts of practical 
applications. Incidentally, nowhere else has it been mentioned that the 
MIDI connections can be used for other purposes. One idea would be to 
use the MIDI interfaces of several STs to link them together (for schools or 
offices, for example). 


1.5.1 The Pins of the 6850 


For those of you readers who aren't very well-acquainted with the 
principles of serial data transfer, we've included some fairly detailed 
descriptions in the pin layout which follows. 


Vss 
This connection is the "ground wire" of the IC. 


RX DATA Receive Data 


This pin receives data; a start-bit must precede the least significant 
data-bit before receipt. 


41 


Abacus Software Atari ST Internals 


Figure 1.5-1 ACIA 6850 


Vss 
RX DATA ( | 
RX CLK ( | 
TX: CLE (0-) 


ag 

oO ~ 

Ln) - 

0 
RTS* oe ‘Oo i D 2 
TX DATA & io p38 
IRQ* ee » pug 
S570 ne ay ‘a ee pers 
CS 2 ee & D 6 
cs 1 | r Al D 7 
Tn 2  : 
Vec & a R/w* 
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RX CLK Receive Clock 
This pin signal determines baud-rate (speed at which the data is 
received), and is synchronize to the incoming data. The 
frequency of RX CLK is patterned after the desired transfer 
speed and after the internally programmed division rate. 


TX CLK Transmitter Clock 
Like RX CLK, only used for transmission speed. 


RTS Request To Send 
This output signals the processor whether the 6850 is low or 
high; mostly used for controlling data transfer. A low output 
will, for example, signal a modem that the computer 1s ready to 
transmit. 


TX DATA Transmitter Data 
This pin sends data bit-wise (serially) from the computer. 


IRQ Interrupt Request 
Different circumstances set this pin low, signaling the 68000 
processor. Possible conditions include completed transmission 
or receipt of a character. 


CS 0,1,2 Chip Select 
These three lines are needed for ACIA selection. The relatively 
high number of CS signals help minimize the amount of 
hardware needed for address decoding, particularly in smaller 
computer systems. 


RS Register Select 
This signal communicates with internal registers, and works 
closely with the R/W signal. We shall talk about these registers 
later. 


Vee Voltage 
This pin is required of all ICs -- this pin gets an operating voltage 
of SV. 


R/W Read/Write 
This tells the processor the "direction" of data traveling through 
the ACIA. A high signal tells the processor to read data, and low 
writes data in the 6850. 
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E Enable 
The E-signal determines the time of reading/writing. All 
read/write processes with this signal must be synchronous. 


DO - D7 Data 
These data lines are connected to those of the 68000. Until the 
ACIA is accessed, these bidirectional lines are all high. 


DCD Data Carrier Detect 
A modem control signal, which detects incoming data. When 
DCD is high, serial data cannot be received. 


CTS Clear To Send 
CTS answers the computer on the signal RTS. Data transmission 
is possible only when this pin is low. 


1.5.2 The Registers of the 6850 


The 6850 has four different registers. Two of these are read only. Two of 
them are write only. These registers are distinguished by R/W and RS, 
after the table below: 


0 0 Control Register write 
0 - Sender Register write 
1 0 Status Register read 
i 1 Receive Register read 


The sender/receiver registers (also known as the RX- and TX- buffers) are 
for data transfer. When receiving is possible, the incoming bits are put in a 
shift register. Once the specified number of bits has arrived, the contents of 
the shift register are transferred to the TX buffer. The sender works in 
much the same way, only in the reverse direction (RX buffer to sender shift 
register). 


Abacus Software 


Lt cin pumas fe Tee AA GAEL: Pee DO OPS. Oe oe OT 


Th n i 


The eight-bit control register determines internal operations. To solve the 
problem of controlling diverse functions with one byte, single bits are set up 


These bits determine by which factor the transmitter and receiver 
clock will be divided. These bits also are joined with a master 
reset function. The 6850 has no separate reset line, so it must be 


accomplished through software. 


These so-called Word Select bits tell whether 7 or 8 data-bits are 
involved; whether 1 or 2 stop-bits are transferred; and the type of 


as below: 
CR 0,1 
CR1 CRO 
0 0 
0 i 
1 © 
1 1 
CR 2,3,4 
parity. 
CR4 CR 
O O 
O © 
0 1 
0 1 
1 0 
i 0 
i 1 
L 1 
CR 6,5 
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RXCT RI ITXCLUNK “Wi tnont ao1V71Ss10n 


RXCLK/TXCLK by -16 
RXCLK/TXCLK by 64 


Master RESET 


C) 
NO 


POoOorRrOrFOFRO W 
© wM7O On I NY XI 


sequence of null bits. 


databits, 
databits, 
databits, 
databits, 
databits, 
databits, 
databits, 
databits, 
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SLOppItS; 
stopbits, 


stonmbit, 
storpbit, 
stopbit, 
Stopbit, 
stopbit, 
Sroobit-: 


even 
odd 
even 
odd 
no 
no 
even 
odd 


(Lor Mips) 
(for keyboard) 


parity 
parity 
parity 
parity 
parity 
parity 
parity 
parity 


These Transmitter Control bits set the RTS output pin, and allow 
or prevent an interrupt through the ACIA when the send register 
is emptied. Also, BREAK signals can be sent over the serial 
output by this line. A BREAK signal is nothing more than a long 
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CR6 CR5 
Q 0 RTS low, transmitter IRQ disabled 
0 1 RTS low, transmitter IRQ enabled 
id 0 RTS high, transmitter IRQ disabled 
1 1 RTS low, transmitter IRQ disabled, BREAK 


sent 


CR 7 
The Receiver Interrupt Enable bit determines whether the receiver 
interrupt will be on. An interrupt can be caused by the DCD line 
changing from low to high, or by the receiver data buffer filling. 
Besides that, an interrupt can occur from an OVERRUN (a - 
received character isn't properly read from the processor). | 


CR7 3 
0 Interrupt disabled 
1 Interrupt enabled 


The Status Resist 


The Status Register gives information about the status of the chip. It also 
hes its information coded into individual bytes. 


SKO 
When this bit is high, the RX data register is full. The byte must 
be read before a new character can be received (otherwise an 
OVERRUN happens). 

SR1 
This bit reflects the status of the TX data buffer. An empty 
register sets the bit. 

SR2 


A low-high change on pin DCD sets SR2. If the receiver 
interrupt is allowable, the IRQ will be cancelled. The bit is 
cleared when the status register and the receiver register are read. 
This also cancels the IRQ. SR2 register remains high if the 
signal on the DCD pin is still high; SR2 registers low if DCD 
becomes low. 
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SR3 


SR4 


SR5 


SR6 


SR 7 


This line shows the status of CTS. This signal cannot be altered 
by a master reset, or by ACIA programming. 


Shows "Frame errors". Frame errors are when no stop-bit is 
recognized in receiver switching. It can be set with every new 
character. 


This bit displays the previously mentioned OVERRUN 
condition. SR5 is reset when the RX buffer is read. 


This bit recognizes whether the parity of a received character is 
correct. The bit is set on an error. 


This signals the state of the IRQ pins; this bit makes it possible to 
switch several IRQ lines on one interrupt input. In cases where 
an interrupt is program-generated, SR7 can tell which IC cut off 
the interrupt. 


The ACIAs in the ST 
The ACIAs have lots of extras unnecessary to the ST. In fact, CTS, DCD 
and RTS are not connected. 


The keyboard ACIA lies at the addresses $FFFCOO and $FFFCO02. Built-in 
parameters are: 8-bit word, 1 stopbit, no parity, 7812.5 baud (500 


kHz/64). 


The parameters are the same for the MIDI chip, EXCEPT for the baud rate, 
which runs at 31250 baud (500 kHz/16). 
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1.6 The YM-2149 Sound Generator 


The Yamaha YM-2149, a PSG (programmable sound generator) in the same 
family as the General Instruments AY-3-8190, is a first-class sound 
synthesis chip. It was developed to produce sound for arcade games. The 
PSG also has remarkable capabilities for generating/altering sounds. 
Additionally, the PSG can be easily controlled by joysticks, the computer 
keyboard, or external keyboard switching. The PSG has two bidirectional 
8-bit parallel ports. Here's some general data on the YM-2149: 


¢ three independently programmable tone generators 
¢ a programmable noise generator 

¢ complete software-controlled analog output 

¢ programmable mixer for tone/noise 

¢ 15 logarithmically raised volume levels 

¢ programmable envelopes (ASDR) 

* two bidirectional 8-bit data ports 

¢ TTL-compatible 

¢ simple 5-volt power 


The YM-2149 has a total of 16 registers. All sound capabilities are 
controlled by these registers. 


The PSG has several "functional blocks" each with its own job. The tone 
generator block produces a square-wave sound by means of a time signal. 
The noise generator block produces a frequency-modulated Square-wave 
signal, whose pulse-width simulates a noise generator. The mixer couples 
the three tone generators’ output with the noise signal. The channels may 
be coupled by programming. 


The amplitude control block controls the output volume of the three 
channels with the volume registers; or creates envelopes (Attack, Decay, 
Sustain, Release, or ADSR), which controls the volume and alters the 
sound quality. 


The D/A converter translates the volume and envelope information into 


digital form, for external use. Finally one function block controls the two 
I/O ports. 
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Figure 1.6-1 Sound chip YM-2149 
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1.6.1 Sound Chip Pins 


Vss: 
This is the PSG ground connection. 
INGw 
Not used. 
ANALOG B: 
This is the channel B output. Maximum output voltage is 1 vss. - 
ANALOG A: 
Works like pin 3, but for channel A. 
INC g 
Not used. 
IOB7 - 0: | 
The IOB connections make up one of the two 8-bit ports on the 
chip. These pins can be used for either input or output. Mixed 
operation (input and output combined) is impossible within one 
port, however both ports are independent of one another. 
IOA7 - 0: 
Like IOB, but for port A. 
CLOCK: 
All tone frequencies are divided by this signal. This signal 
operates at a frequency between 1 and 2 mHz. 
RESET: 
A low signal from this pin resets all internal registers. Without a 
reset, random numbers exist in all registers, the result being a 
rather unmusical "racket". 
A9: 


This pin acts as a chip select-signal. When it is low, the PSG 
registers are ready for communication. 
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A8: 
Similar to A9, only it is active when high. 


TES 12: 
Test2 is used for testing in the factory, and is unused in normal 
operation. 


BDIR & BCI,?2: 
The BDIR (Bus DIRection), BC1 and BC2 (Bus Control) pins 
control the PSG's register access. 


WO 
oS, 
4 
NO 
4 
7 

we 


Inactive 
Latch address 
Inactive 

Read from PSG 
Latch address 
Inactive 
Write to PSG 
Latch address 


PrRrPrFOODOO 
PrROdDrFrFrROOW 
MPOoOorFrOrOorFr OW 


Only four of these combinations are of any use to us; those with a 
5+ voltage running over BC2. So, here's what we have left: 


BDI .BCl Fuaccron 

0 0 Inactive, PSG data bus high 

0 1 Read PSG registers 

ik OQ Write PSG registers 

1 1 Latch, write register number(s) 


DAO - 7: 
These pins connect the sound chip to the processor, through the 
data bus. The identifier DA means that both data and (register) 
addresses can be sent over these lines. 


ANALOG C: 
Works with channel C (see ANALOG B, above). 


LESEL: 
See TEST2. 


Vee: 
+5 volt pin. 
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1.6.2 The 2149 Registers and their Functions 


Now let's look at the functions of the individual registers. One point of 
interest: the contents of the address register remain unaltered until 
reprogrammed. You can use the same data over and over, without having 
to send that data again. 


Reg 0,1: 
These register determine the period length, and the pitch of 
ANALOG A. Not all 16 bits are used here; the eight bits of 
register O (set frequency) and the four lowest bits of register 1 
(control step size). The lower the 12-bit value in the register, the 


higher the tone. 

Reg 2,3: 
Same as registers O and 1, only for channel B. 

Reg 4,5: 
Same as registers 0 and 1, only for channel C. 

Reg 6: 
The five lowest bits of this register control the noise generator. 
Again, the smaller the value, the higher the noise "pitch". 

Reg 7: 
Bit O:Channel A tone on/off O=on /1=off 
Bit 1:Channel B tone on/off O=on /1l=off 
Bit 2:Channel C tone on/off O=on /1=off 
Bit 3:Channel A noise on/off O=on /1l=off 
Bit 4:Channel B noise on/off O=on /1l=off 
Bit 5:Channel C noise on/off O=on /1l=off 
Bit. 6220rt. A. ins ourput O=in /1=out 
Bit. J Porl..b.10/ourpue O=in /1=out 
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Figure 1.6-2 Envelopes of the PSG 
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Reg 8: 
Bits 0-3 of this register control the signal volume of channel A. 
When bit 4 is set, the envelope register is being used and the 
contents of bits 0-3 are ignored. 


Reg 9: 
Same as register 8, but for channel B. 


Reg 10: 
Same as register 8, but for channel C. 


Reg 11,12: 


The contents of register 11 are the low-byte and the contents of ~ | 


register 12 are the high-byte of the sustain. 


Reg 13: 
Bits 0-3 determine the waveform of the envelope generator. The 
possible envelopes are pictured in Figure 1.6-2. 


Reg 14,15: 
These registers comprise the two 8-bit ports. Register 14 is 
connected to Port A and register 15 is connected to Port B. If 
these ports are programmed as output (bits 7 and 8 of register 7) 
then values may be sent through these registers. 
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1.7 VO Register Layout in the ST 


The entire I/O range (all peripheral ICs and other registers) is controlled by a 
32K address register -- $FF8000 - $FFFFFF. Below is a complete table of 
the different registers. CAUTION: The I/O section can be accessed only in 
supervisor mode. Any access in user mode results in a bus-error. 


SFF8000 Memory configuration 
SFF8200 Video display register 
SFF8400 Reserved 

SFF 8600 DMA/disk controller 

SFF 8800 Sound. chip 

SFFFAOO MFP 68901 

SFFFCOO ACIAs for MIDI and keyboard 


The addresses given refer only to the start of each register, and supply no 
hint as to the size of each. More detailed information follows. 


$FF8000_ Memory Configuration 


There is a single 8-bit register at $FF8001 in which the memory 
configuration is set up (four lowest bits). The MMU-IC is designed for 
maximum versatility within the ST. It lets you use three different types of 
memory expansion chips: 64K, 256K, and the 1M chips. Since all of these 
ICs are bit-oriented instead of byte-oriented, 16 memory chips of each type 
are required for memory expansion. The identifier for 16 such chips 
(regardless of memory capacity) is BANK. So, expansion is possible to 
128 Kbyte, 512 Kbyte or even 2 Megabytes. 


MMU can control two banks at once, using the RAS- and CAS- signals. 
The table on the next page shows the possible combinations: 
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mor 
3-0 Bank 0O Bank 1 
0000 128K 128K 
0001 128K 512K 
0010 128K 2M 
0011 reserved 
0100 OL 2K 128K 
0101 Si2k 512K 
0100 oLZK 2 M,normally reserved 
0100 reserved 
LO000 2M 128K 
1001 2M Sik 
1010 2M 2M 
LOLs reserved 
i ©: < reserved 


The memory configuration can be read from or written to. 


FF32 I Displ 


This register is the storage area that determines the resolution and the color 
palette of the video display. 


Screen memory position (high-byte) 
Screen memory position (low-byte) 


S—bit 
S=bit 


SFF8201 
SFF8203 


These two read/write registers are located at the beginning of the 32K videc | 
RAM. 


In order to relocate video RAM, another register is used. This register is 
three bytes long and is located at $FF8205. Video RAM can be relocated in 
256-byte increments. Normally the starting address of video RAM is 
$78000. 


SFF8205 8-bit Video address pointer (high-byte) 
SFF 8207 8-bit Video address pointer (mid-byte) 
SFF 8209 8-bit Video address pointer (low-byte) 


These three registers are read only. Every three microseconds, the contents 
of these registers are incremented by 2. 
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SFF820A BIT Synchronization mode 
140 
> :-- Q=internal,1l=external synchronization 
:---- O=60 Hz, 1=50Hz screen frequency 


The bottom two bits of this register control synchronization mode; the 
remaining bits are unused. If bit 0 is set, the HSync and VSync impulses 
are shut off, which allows for screen synchronization from external sources 
(monitor jack). This offers new realm of possibilities in video, 
synchronization of your ST and a video camera, for example. 


Bit 1 of the sync-mode register handles the screen frequency. This bit is 
useful only in the two "lowest" resolutions. High-res operation puts the ST 
at a 70 Hz screen frequency. 


Sync mode can be read/written. 


SFF 8240 16=bD2at Color palette register 0 
SFF8242 2O-Da. 6 Color palette register 1 


Color palette registers 2-13 


SFF825C 16-bit Color palette register 14 
SFF825E 16-bit Color palette register 15 


Although the ST has a total of 512 colors, only 16 different colors can be 
displayed on the screen at one time. The reason for this is that the user has 
16 color pens on screen, and each can be one of 512 colors. The color 
palette registers represent these pens. All 16 registers contain 9 bits which 
affect the color: 


FEDCBA9876543210 
bide sa AXX. XXX. XXX 


The bits marked X control the registers. Bits 0-2 adjust the shade of blue 
desired; 4-6, green hue; and 8-A, red. The higher the value in these three 
bits, the more intense the resulting color. 


Middle resolution (640 X 200 points) offers four different colors; colors 4 
through 15 are ignored by the palette registers. 


When you want the maximum of 16 colors, it's best to zero-out the contents 
of the palette registers. 
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High-res (640 X 400 points) gives you a choice on only one "color"; bit 0 
of palette register 0 is set to the background color. If the bit is cleared, then 
the text is black on a light background. A set bit reverses the screen (ight 
characters, black background). The color register is a read/write register. 


SFF 8260 Bit Resolution 
jae 8. 
0.0; +820 X 200-points, four focal'planées 
O 1 640 X 200 points, two focal planes 
1 0 640.X.-400:.-points, one focal*planes 


This register sets up the appropriate hardware for the graphic resolution 
desired. ' Ls 


FF D Disk ntroll 

SFF8600 reserved 

SFF8602 reserved 

SFF8604 16-bit FDC access/sector count 


The lowest 8 bits access the FDC registers. The upper 8 bits contain no 
information, and consistently read 1. Which register of the FDC is used 
depends upon the information in the DMA mode control register at 
$FF8606. The FDC can also be accessed indirectly. 


The sector count-register under $FF8604 can be accessed when the — 
appropriate bit in the DMA control register is set. The contents of these 
addresses are both read/write. 


SFF8606 16-bit DMA mode/status 


When this register is read, the DMA status is found in the lower three bits of 
the register. 


Bit O O=no error, 1=DMA error 
Bit 1 O=sector count = null, 1l=sector count<>null 
Bit 2 Condition of FDC DATA REQUEST Signal 


Write access to this address controls the DMA mode register. 
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Bit O unused 
1 


Bit O=pin AO is low 
i=pin AO is high 
Bis 2 O=pin Al is low 
daa), Peles Sh Lah 
Bik O=FDC access 
1=HDC access 
Bit 4 O=access to FDC register 
l=access to sector count register 
Bat:5 O, reserved 
Bit 76 O=DMA on 
1=no DMA 
Batual O=hard disk controller access (HDC) 
1=FDC access 
Bit 8 O=read FDC/HDC registers 
l=write to FDC/HDC registers 
SFF 8609 ‘Sig ols DMA basis and counter high-byte 
SFF860B S=Die DMA basis and counter mid-byte 
SFF860D 8-bit DMA basis and counter low-byte 


DMA transfer will tell the hardware at which address the data is to be 
moved. The initialization of the three registers must begin with the low-byte 
of the address, then mid-byte, then high-byte. 


SFF8800 Sound Chi 


The YM-2149 has 16 internal registers which can't be directly addressed. 
Instead, the number for the desired register is loaded into the select register. 
The chosen registers can be read/write, until a new register number is 
written to the PSG. 


SFF8800 8—bit Read data/Register select 


Reading this address gives you the last register used (normally port A), by 
which disk drive is selected. This can be accomplished with write-protect 
Signals, although these protected contents can be accessed by another 
register. Port A is used for multiple control functions, while port B is the 
printer data port. 
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PORT A 

Bit 0O Page-choice signal for double-sided 
floppy drive 

Ba oA. Drive select signal -- floppy drive 0 
Bait~ 2 Drive select signal -- floppy drive 1 
Bit 3 RS-232 RTS-output | 
Bit 4 RS-232 DTR output 
Bit *5 Centronics strobe 
Bits:6 Freely usable output (monitor jack) 
Bit 7 reserved | 


When $FF8800 is written to, the select register of the PSG is alerted. The 
information in the bottom four bits are then considered as register numbers. — 
The necessary four-bit number serves for writing to the PSG. 
SFF8802 8-bit Write data 

Attempting to read this address after writing to it will give you SFF only, 
while BDIR and BC1 are nulls. 


Writing register numbers and data can be performed with a single MOVE 
instruction. i: 


$FFFA00 MFP 68901 
The MFP's 24 registers 
$FFFA01-$FFFA2F: 


are found at odd addresses from — 


SFFFAO1 8—-bit Parallel port 

SFFFA03 8—bit Active Edge register 
SFFFAOS5 8-bit Data direction 

SFFFAO7 8-bit Interrupt enable A 
SFFFAO9 8—-bit Interrupt enable B 
SFFFAOB 8~-bit Interrupt pending A 
SFFFAOD 8—bit Interrupt pending B 
SFFFAOF 8-bit Interrupt in-service A 
SFFFA11 8-—bit Interrupt in-service B 
SFFFA13 8-bit Interrupt mask A 
SFFFA1S5 8—bit Interrupt mask B 
SFFFA17 8—-bit Vector register 
SFFFA19 8—bit Timer A control 
SFFFA1B 8=—bit Timer B control 
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SFFFA1D 8-bit Timer C & D control 
SFFFAI1F 8-bit Timer A data 
SFFFA21 8-bit Timer B data 
SFFFA23 8-bit Tiner.C data 
SFFFA25 8-bit Timer D data 
SFFFA27 C=pit Sync character 
SFFFA29 8-bit USART control 
SFFFA2B 8—-bit Receiver status 
SERFAZD 8—bit Transmitter status 
SFFFA2F 8-bit USART data 


See the chapter on the MFP for details on the individual registers. 


I/O Port 

Bit O Centronics busy 

Bre tL. RS-232 data carrier detect - pRaneyene 
Biti2 RS-232 clear to send - input 

Bit: is reserved 

Bit 4 keyboard and MIDI interrupt 

Bit.t5 FDC and HDC interrupt 

Bit ‘6 RS-232 ring indicator 

Bit 7 Monochrome monitor detect 


Timers A and B each have an input which can be used by external timer 
control, or send a time impulse from an external source. Timer A is unused 
in the ST, which means that the input is always available, but it isn't 
connected to the user port, so the Centronics busy pin is connected instead. 
You can use it for your own purposes. 


Timer B is used for counting screen lines in conjunction with DE (Display 
Enable). 


The timer outputs in A-C are unused. Timer D, on the other hand, sends 
the timing signal for the MFP's built-in serial interface. 
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The communications between the ST, the keyboard, and musical 
instruments are handled by two registers in the ACIAs. 


SFFFCOO 8—-bit Keyboard ACIA control 
SFFFCO2 8-bit Keyboard ACIA data 
SFFFCO4 8-bit MIDI ACIA control 
SFFFCO6 8-bit MIDI ACIA data 


Figure 1.7-1 I/O Assignments 


2 ACIA’s 6580 


$FFFCOO 
MFP 68901 
$FFFA00 
SOUND AY-3-8910 
$FF8800 
DMA / WD 1770 
_ $FF3600 
RESERVED 
$FF8400 
VIDEO CONTROLLER 
$FF8200 


DATA CONFIGURATION 
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Figure 1.7-2 Memory Map of the ATARI ST 


I/O - Area 


$FF FCOO 


FAOO 


8800 
8600 
8400 
8200 
8000 


$F F 
$F F 


$FF 


SEE-FFFE 


$FC 0000 


$FA 0000 


$07 FFFF 


$00 0000 


192 K 
System ROM 


128 K ROM 
Expansion Cartridge 


512 K RAM 
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16776192 


16775680 


16746496 
16745984 
16745472 
16744960 
16744448 


16711679 


16515072 


16384000 
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BLOCK DIAGRAM of the ATARI ST 
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Chapter Two 


The Interfaces 


2.1 The Keyboard 

2.1.1 The Mouse 

2.1.2 Keyboard commands 

2.2 The Video Connection 
2.3 The Centronics Interface 
2.4 The RS-232 Interface 
2.5 The MIDI Connections 
2.6 The Cartridge Slot 

2.6.1 ROM Cartridges 

2.7 The Floppy Disk Interface 
2.8 The DMA Interface 
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The Interfaces 


2.1 The Keyboard 


Do you think it's really necessary to give a detailed report on something as 
trivial as the keyboard, since keyboards all function the same way? Actually 
the title should read "Keyboard Systems" or something similar. The 
keyboard is controlled by its own processor. You will soon see how this 
affects the assembly language programmer. 


The keyboard processor is single-chip computer (controller) from the 6800 
family, the 6301. Single chip means that everything needed for operation is 
found on a single IC. In actuality, there are some passive components in the 
keyboard circuit along with the 6301. | 


The 6301 has ROM, RAM, some I/O lines, and even a serial interface on 
the chip. The serial interface handles the traffic to and from the main board. 


The advantage of this design is easy to see. The main computer is not 
burdened by having to continually poll the keyboard. Instead it can dedicate 
itself completely to processing your programs. The keyboard processor 
notifies the system if an event occurs that the operating system should be 
aware of. 


The 6301 is not only responsible for the relatively boring task of reading the 
keyboard, however. It also takes care of the rather complicated tasks 
required in connection with the mouse. The main processor is then fed 
simply the new X and Y coordinates when the mouse is moved. N aturally, 
anything to do with the joysticks is also taken care of by the keyboard 
controller. 


In addition, this controller contains a real-time clock which counts in 
one-second increments. 
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Figure 2.1-1 6850 Interface to 68000 
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In Figure 2.1-1 is an overview of the interface to the 68000. As you see, the 
main processors is burdened as little as possible. The ACIA 6850 ensures 
that it is disturbed only when a byte has actually been completely received 
from the keyboard. The ACIA, by the way, can be accessed at addresses 
¢FFFCOO (control register) and $FFFCO2 (data register). The individual 
connection to the keyboard takes place over lines K14 and K15. K indicates 
the plug connection by which the keyboard is connected to the main board. 


The signal that the ACIA has received a byte 1s first sent over line 14 to the 
MFP 68901 which then generates an interrupt to the 68000. The clock 
frequency of SOOKHz comes from GLUE. From this results the "odd" 
transfer rate of 7812.5 baud. 


In case you were surprised that data can also be sent to the keyboard 
processor, you will find the solution to the puzzle in Chapter 2.1.2. 


The block diagram of the keyboard circuit is found in Figure 2.1-2. The 
function is as simple as the figure is easy to read. The processor has 4K of 
ROM available. The 128 bytes of RAM is comparatively small, but it is 
used only as a buffer and for storing pointers and counters. 


The lines designated with K are again the plug connections assigned to the 
main board. With few exceptions, the connections for the joystick and 
mouse are also put through. K16 is the reset line from the 68000. K15 
carries the send data from the 6850, K14 the send data from the 6301. 


The I/O ports 1(0-7), 3(1-7), and 4(0-7) are responsible for reading the 
keyboard matrix. One line from ports 3 and 4 is pulled low in a cycle. The 
state of port 1 is the checked. If a key is pressed, the low signal comes 
through on port 1. 


Each key can be identified from the combination of value placed on ports 3 
and 4 and the value read from port 1. 


If none of the lines of Port 3 and 4 are placed low and a bit of port 1 still 
equals zero, a joystick is active on the outer connector 1. The data from 
outer connector 0, to which a mouse or a joystick can be connected, does 
not come through by chance since it must first be switched through the 
NAND gate with port 2 (bit 0). The buttons on the mouse or the joystick 
then arrive at port 2 (1 and 2). 
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Figure 2.1-2 Block Diagram of Keyboard Circuit 
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The assignments of the K lines to the signal names on the outer connector 
are found in the next section. 


The 6301 processor is completely independent, but it can also be configured 
so that it works with an external ROM. Some of the port lines are then 
reconfigured to act as address lines. The configuration the processor 
assumes (one of eight possibilities) depends on the logical signal placed on 
port 2 (bits 0-2) during the reset cycle. All three lines high puts the 
processor in mode 7, the right one for the task intended here. But bits 1 and 
2 depend on the buttons on the mouse. If you leave the mouse alone while 
powering-up, everything will be in order. If you hold the two buttons 
down, however, the processor enters mode 1 and makes a magnificent 
belly-flop, since the hardware for this operating mode is not provided. You 
notice this by the fact that the mouse cursor does not move on the screen if 
you move the mouse. Only the reset button will restore the processor. 


2.1.1 The Mouse 


The construction of this little device is quite simple, but effective. 
Essentially, it consists of four light barriers, two encoder wheels, and a 
drive mechanism. 


The task of the mouse is to give the computer information about its 
movements. This information consists of the components: direction on the 
X-axis, direction on the Y-axis, and the path traveled on each axis. 


In order to do this, the rubber-covered ball visible from the outside drives 
two encoder wheels whose drive axes are at angle of 90 degrees to each 
other. The one or the other axis rotates more or less, forwards or 
backwards, depending on the direction the mouse is moved. 


It is no problem to determine the absolute movement on each axis. The 
encoder wheels alternately interrupt the light barriers. One need only count 
the pulses from each wheel to be informed about the path traveled on each 
axis. 
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Figure 2.1.1-1 The Mouse 
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It is more difficult when the direction of movement is also required. The 
designers of the mouse used a convenient trick for this. There are not one, 
but two light barriers on each encoder wheel. They are arranged such that 
they are not shielded by the wheel at precisely the same time, but one 
shortly after the other. This arrangement may not be so clear in Figure 
2.1.1-1, so we'll explain it in more detail The direction can be determined 
by noticing which of the two light barriers is interrupted first. This 1s why 
the pulses from both light barriers are sent out, making a total of four. 
Corresponding to their significance they carry the names XA, XB, YA, YB. 


The two contacts which you see on the picture represent the two buttons. 


The large box on the picture is a quad operational amplifier which converts 
the rather rough light-barrier pulses into square wave signals. | 


In Figure 2.1.1-2 is the layout of the control port on the computer, as you 
see it when you look at it from the outside. The designation behind the slash 
applies when a joystick is connected and the number in parentheses is the 
pin number of the keyboard connector. 


Port 0 
l XB/UP (K12) 
Z XA/DOWN (K10) 
3 YA/LEFT (K9) 
4 YB/RIGHT (K8) 
6 LEFT BUTTON/FIRE (K11) 
7 +5V (K13) 
8 GND (K1) 
‘9 RIGHT BUTTON (K6) 
Port 1 
1 UP (K7) 
2 DOWN : (K5) 
3 LEFT (K4) 
4 RIGHT (K3) 
5 Port O enable | (K17) 
6 FIRE (K6) 
| +5V (K13) 
8 GND (K1) 
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2.1.2 Keyboard commands 


The keyboard processor "understands" some commands pertaining to such 
things as how the mouse is to be handled, etc. You can set the clock time, 
read the internal memory, and so on. You can find an application example in 
the assembly language listing on page 80 (after command $21). 


The "normal" action of the processor consists of keeping an eye on the 
keyboard and announcing each keypress. This is done by outputting the 
number of the key when the key is pressed. When the key is released the 
number is set again, but with bit 7 set. The result of this is that no key 
numbers greater than 127 are possible. You can find the assignment of the 
key numbers to the keys at the end of this section in figure 2.1.2-1. In 
reality these numbers only go up to 117 because values from $F6 up are 
reserved for other purposes. There must be a way to pass more information 
than just key numbers to the main processor, information such as the clock 
time or the current position of the mouse. This cannot be handled in a single 
byte but only in something called a package, so the bytes at $F6 signal the 
start of a package. Which header comes before which package is explained 
along with the individual commands. 


A command to the keyboard processor consists of the command code (a 
byte) and any parameters required. The following description is sorted 
according to command bytes. 


$07 
Returns the result of pressing one of the two mouse buttons. A parameter 
byte with the following format is required: 
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Bit O =1: The absolute position is returned when a 
mouse button is pressed. Bit 2 must =0. 
Bit 1 =1: The absolute position is returned when a 
mouse button is released. Bit 2 must =0Q. 
Bit 2 =1: The mouse buttons are treated like 


normal keys. The left button is key 
number $74, the right is $75. 
Bike: 3-7 must always be zero. 


$03 

Returns the relative mouse position from now on. This command tells the 

keyboard processor to automatically return the relative position (the distance 

from the previous position) whenever the mouse is moved. A movement is 
iven when the number of encoder wheel pulses has reached a given 

threshold. See also $0B. A relative mouse package looks like this: 


1 byte Header in range S$F8-SFB. The two lowest 
bits of the header indicate the condition 
of the two mouse buttons. 

1 byte Relative X-position (signed!) 

1 byte Relative Y-position (signed!) 


If the relative position changes substantially between two packages so that 
the distance can no longer be expressed in one byte, another package is 
automatically created which makes up for the remainder. 


$09 

Returns the absolute mouse position from now on. This command also sets 
the coordinate maximums. The internal coordinate pointers are at the same 
time set to zero. The following parameters are required: 


1 word Maximum X-coordinate 
1-word Maximum Y-coordinate 


Mouse movements under the zero point or over the maximums are not 
returned. 


$0A 

With this command it is possible to get the key numbers of the cursor keys 
instead of the coordinates. A mouse movement then appears to the operating 
system as if the corresponding cursor keys had been pressed. These 
parameters are necessary: 
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1 byte Number of pulses (X) after which the key 
number for cursor left (or right) will be 
sent: 

1 byte Number of pulses (Y) after which the key 
number for cursor up (or down) will be sent. 


$OB 

This command sets the trigger threshold, above which movements will be 
announced. A certain number of encoder pulses elapse before a package is 
sent. This functions only in the relative operating mode. The following are 
the parameters: | 


1 byte Threshold in X-direction 
1 byte Threshold in Y-direction 
$0C 


Scale mouse. Here is determined how many encoder pulses will go by 
before the coordinate counter is changed by 1. This command is valid only 
in the absolute. The following parameters are required: 


1 byte X scaling 
1 byte Y scaling 
$0D 


Read absolute mouse position. No parameters are required, but a package of 
the following form is sent: 


1 byte Header = SF7 
1 byte Button status 
Bit 0 = 1: Right button was pressed since the 
last read 
Bit 1 = 1: Right button was not pressed 
Bit 2 = 1: Left button was pressed since the 
last read 
Bit 3 = 1: Left button was not pressed 


From this strange arrangement you can determine that the state of a button 
has changed since the last read if the two bits pertaining to it are zero. 


1 word Absolute X-coordinate 
1 word Absolute Y-coordinate 
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$0E 
Set the internal coordinate counter. The following parameters are required: 


1. byte =O as fill byte 
1 word X-coordinate 

1 word Y-coordinate 
SOF 


Set the origin for the Y-axis is down (next to the user). 


$10 
Set the origin for the Y-axis is up. 


$11 
The data transfer to the main processor is permitted again (see $13). 
Any command other than $13 will also restart the transfer. 


$12 
Turn mouse off. Any mouse-mode command ($08, $09, $0A) turns the 
mouse back on. If the mouse is in mode $0A, this command has no effect. 


$13 

Stop data transfer to main processor. 

NOTE: Mouse movements and key presses will be stored as long as the 
small buffer of the 6301 allows. Actions beyond the capacity of the buffer 
will be lost. 


$14. 
Every joystick movement is automatically returned. The packages sent have 
the following format: 


1 byte Header = SFE or SFF for joystick 0/1 
1 byte Bits 0-3 for the position (a bit for each 
direction); :-D1b 7] <ror- the button 


$15 
End the automatic-return mode for the joystick. When needed, a package 
must be requested with $16. 


$16 
Read joystick. After this command the keyboard sends a package as 
described above. 
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$17 
Joystick duration message. One parameter is required. 


1 byte Time between two messages in 1/100 sec. 


From this point on, packages of the following form are sent continuously 
(as long as no other mode is selected): 


1 byte Bit 0 for the button on joystick 1, bit 1 


LOL thet: -Of-- joystick 0 
1 byte Bits 0-3 for the position of joystick (- 


bits 4-7 for the position of joystick 0 


NOTE: The read interval should not be shorter than the transfer channel 
needs to send the two bytes of the package. 


$18 

Fire button duration message. The condition of the button in joystick 1 (!) is 
continually tested and the result packed into a byte. This means that a 
message byte contains 8 such tests, whereby bit 7 is the most recent. The 
keyboard controller determines the time between byte fetches by the main 
processor. This time is divided into eight equal intervals in which the button 
is polled. The polling then takes place as regularly as possible. This mode 
remains active until another command is received. 


$19 

Cursor key simulation mode for joystick 0 (!). The current position of th 
joystick is sent to the main processor as if the corresponding cursor keys 
had been pressed (as often as necessary). To avoid having to explain the 
same things for the following parameters, here are the most important: All 
times are assumed to be in tenths of seconds. R indicates the time, when 
reached, cursor clicks will be sent in intervals of T. After this the interval is 
V. If R=0, only V is responsible for the interval. N aturally, this mechanism 
comes into play only when the joystick is held in the same position for 
longer than T or R. 


1 byte RX 
1 byte RY 
1 byte TX 
1 byte Ty 
i*byte VX 
1 byte VY 
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$1A are | 
Turn off joysticks. Any other joystick command turns them on again. 


1B 
se clock time. This command sets the internal real-time clock in the 
keyboard processor. The values are passed in packed BCD, meaning a digit 
0-9 for each half byte, yielding a two-digit decimal number per byte. The 
following parameters are necessary: 


1 byte Year; “Ewo digit .(55;..8b6,':ecc.) 
ee Month, £wo- d101..(12;, Ul, etc; 
1 byte Day, two G1lgit (31; 01,02;-.eCC.) 
1 byte Hours, two digit 

1 byte Minutes, two digit 

1 byte Seconds, two digit 


Any half byte which does not contain a valid BCD digit (such as F) 1s 
ignored. This makes it possible to change just part of the date or clock time. 


$1C 

Read clock time. After receiving this command the keyboard processor 
returns a package having the same format as the one described above. A 
header is added to the package, however, having the value $FC. 


$20 

Load memory. The internal memory of the keyboard processor (naturally 
only the RAM in the range $80 to $FF makes sense) can be written with this 
command. It is not clear to us of what use this is since according to our 
investigations (we have disassembled the operating system of the 6301), no 
RAM is available to be used as desired. Perhaps certain parameters can be 
changed in this manner which are not accessible through "legal" means. 
Here are the parameters: 


1 word Start address 
1 byte Number of bytes (max. 128) 
Data bytes (corresponding to the number) 


The interval at which the data bytes will be sent must be less than 20 msec. 
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$21 | 
Read memory. This command is the opposite of $20. These parameters are 


required: 
1 word Address at which to read 
A package having the following format is returned: 


1 byte Header 1 =SF6. This is the status header 
which precedes all packages containing any 
operating conditions of the keyboard 
processor. We will come to the general 
status messages shortly. 

1 byte Header 2 =$20 as indicator that this 
package carries the memory contents. 

6 bytes Memory contents starting with the address 
given in the command. 


Here is a small program which we used to read the ROM in the 6301 and 
output it to a printer. Here you also see how the status packages arrive from 
the keyboard. These are normally thrown away by the 68000 operating 
system. Section 3.1 contains information about the GEMDOS and XBIOS 
calls used. 


PLE equ O 
chout equ 3 
gemdos equ : 
bios equ Lo 
xbios equ 14 
stvec equ 12 
rdm equ $21 
wrkbd equ aS 
kbdvec equ 34 
term equ 0 


Star c: 
move.w #kbdvec,-(a7) 
trap #xbios 
addq.l #2,a7 
move.l d0,a0 
lea keyin,al 
move.l d0,savea_ 
move.l stvec(a0),save 
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wait: 


DuLoOuUT:: 


bytout: 


hexout: 


chrout: 


exit: 


lea 


move .b 
bsr 
dbra 
rcs 


movea.w 


fee age ©. 
andi.w 
lea 
move .b 
LS Ww 
move .W 
andi.w 
move.b 
move .W 
move .w 
lsr.w 
bsr 
move .W 
bsr 
move.b 


move .W 
move .W 
move .W 
trap 
addq.1 
rcs 


movea 
move.l1 


al, stvec (a0) 
#S£000,da4 Starting address 


ad4,tbuf+l Current address 
keyout 


rbuf 

wait 

#5,d06 

bufout 

#6,04 Ending address? 
loop 

exit 


rbuf+2,a4 


(a4) +,d0 
hexout 
dadé,bytout 


CuUs,al 

#4,da0 
#15,da0 
table,a3 
O{(a3,c0) ,dZ 
#8,02 

r= ro 0) 
#15,d0 

Uig5 C0) ,a2 
d2,d0 

a2,-~( (al) 
#8,da0 
chrout 

(a7) +,da0 
chrout 

7" "C0 


d0,-(a?7) 
#prt,-(a7) 
#chout, - (a7) 
#bios 

#6,a7 


savea, a0 
save, stvec (a0) 
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keyout: 


keyin: 


repin: 


table: 


move .W 
Erap 


#term, -(a7) 
#gemdos 


rbuf 

tbohuf 

t2,- (al) 
#wrkbd, - (a7) 
#xbios 
#8,a7 


#7,a0 
TOUT, a 
,a0) +, lal}y> 
d0,repin 


"0123456789ABCDEF" 


Q. 

W 
TOTrFrF OS 
KR © 


ram 
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$22 

Execute routine. With this command you can execute a subroutine in the 
6301. Naturally, you must know exactly what it does and where it is 
located, so long as you have not transferred it yourself to RAM with $20 
(assuming you found some free space). The only required parameters are: 


1 word Start address 


Status messages 

You can at any time read the operating parameters of the keyboard by 
simply adding $80 to the command byte with which you would to set the 
operating mode (whose parameters you want to know). You then get a 
status package back (header=$F6), whose format corresponds exactly to 
those which would be necessary for setting the operating mode. 


An example makes it clearer: you want to know how the mouse is scaled. 
So you send as the command the value $8C (since $0C sets the scaling). 
You get the following back: 


1 byte Status header =SF6 
1 byte X-scaling 
1 byte Y-scaling 


This is the same format which would be necessary for the command $0C. 
For commands which do not require parameters, you get tht evoked 
command back as such. For example, say you want to know what operating 
mode the joystick is in ($14 or $15). You send the value $94 (or $95, it 
makes no difference). As status package you receive, in addition to the 
header, either $14 or $15 depending on the operating mode of the joystick 
handler. 


Allowed status checks are: $87, $88, $89, $8A, $8B, $8C, $8F, $90, $92, 
$94, $99, and $9A. 


In conclusion we have a tip for those for whom the functions of the 
keyboard are too meager and who want to give it more "intelligence". The 
processor 6301 is also available in "piggy-back" version, the 63P01 
(Hitachi). This model does not have ROM built in, but has a socket on the 
top for an EPROM of type 2732 or 2764 (8K!). You can then realize your 
own ideas and, for example, use the two joystick connections as universal 
4-bit I/O ports, for which you can also extend the command set in order to 
access the new functions from the XBIOS as well. 
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Figure 2.1.2-1 ATARI ST Key Assignments 
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4.2 The Video Connection 


Without this, nothing would be displayed. You would be typing blind. 
You'll notice the many pins on the connection. Naturally more lines are 
required for hooking up an RGB monitor than for a monochrome screen, 
but seven would be enough. There is also something special about the 
remaining lines. In Figure 2.2-1 you find a block diagram in which you can 
see how the video connection is tied to the system. The numbering of the 
pins is given on the figure on the next page, as you can see, when you look 
at the connector from the outside. Here is the pin layout: 


1 AUDIO OUT. This connection comes from the amplifier 
connected to the output of the sound chip. A high-impedance 
earphone can be attached here if you do not use the original 
monitor. 


2 COMPOSITE VIDEO is the connection from 9-12. This is not 
available on the early 520ST or 1040 ST. 


3 GPO, General Purpose Output. This connection is available for 
your use. The line has TTL levels and comes from I/O port A bit 6 
of the sound chip. 


4 MONOCHROME DETECT. If this line, which leads to the 17 
input of the MFP 68901, is low, the computer enters the 
high-resolution monochrome mode. If the state of the line changes 
during operation, a cold start is generated. 


S AUDIO IN leads to the input of the amplifier described in 1 and is 
there mixed with the output of the sound chip. | 


6 GREEN is the analog green output of the video shifter. 
7 RED. Red output. 


8 +12 control voltage for color televisions with video connectors. 
Atari 520ST = GROUND. 


9 HORIZONTAL SYNC is responsible for the horizontal beam 
return of the monitor. | 
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Figure 2.2-1 Diagram of Video Interface 
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10 BLUE is the analog blue output of the video shifter. 


11 MONOCHROME provides a monochrome monitor with the 
intensity signal. 


12 VERTICAL SYNC takes care of the beam return at the end of the 
screen. 


13 GROUND. 
A tip for the hardware hobbyist: 


A plug to fit this connector is not available. If you want to make a plug for 
connecting other monitors, simply use a piece of perf board in which you 
have soldered pins, since the pins are fortunately organized in a 1/10" array. 
Pin 13 is out of order, but it is not needed since pin 8 is also available for 
ground. 


Figure 2.2-2 Monitor Connector 
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2.3 The Centronics Interface 


A standard Centronics parallel printer can be connected to this interface, 
provided that you have the proper cable. As you can see in Figure 2.3-2, the 
connection to the system is somewhat unusual. The data lines and the strobe 
of the universal port of the sound chip are used. So you find these too on 
the picture, in which the other lines, which will not be described in the 
section, will not disturb you. They belong to the disk drive and RS-232 
interface and are handled there. 


Here is the pin description: 


1 -STROBE indicates the validity of the byte on the data lines 
to the connected device by a low pulse. 


2-9 DATA 


Li BUSY is always placed high by the printer when it is not 
able to receive additional data. This can have various causes. 
Usually the buffer is full or the device is off line. 


18-25 GROUND. 
All other pins are unused. 


A tip for making a cable. Get flat-cable solderless connectors. You neec 
type D25-subminiature, a Cinch 36-pin (3M,AMP) and the appropriate 
length of 25-conductor flat ribbon cable. You squeeze the connectors on the 
cable so that pins 1 match up on both sides (they are connected together). 
The other connections then match automatically. Note that there will 
naturally be some pins free on the printer side. 


Figure 2.3-1 Printer Port Pins 
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Figure 2.3-2 Centronics Connection 
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2.4 The RS-232 Interface 


This interface usually serves for communication with other computers and 
modems. You can also connect a printer here. Note the description of pin 5! 


Figure 2.4-1 shows the connection to the system. Normally you don't have 
to do any special programming to use this interface. It is taken care of by the 
operating system. Here the control of the interface is not controlled by a 
special IC (UART) as is usually the case, but the lines are serviced more or 
less “by hand." The shift register in the MFP is used for this purpose. The 
handshake lines however come from a wide variety of sources. Note this in — 
the following pin description: 


1 CHASSIS GROUND (shield) 
This 1s seldom used. 


2. .TxD 
Send data 
3 RxD 
Receive data 
4 RTS 


Ready to send comes from I/O port A bit 3 of the sound 
chip and is always high when the computer is ready to 
receive a byte. On the Atari, this signal is first placed low 
after receiving a byte and is kept low until the byte has 
been processed. 


S.- 4275 

Clear to send of a connected device is read at interrupt 
input 12 of the MFP. At the present time this signal is 
handled improperly by the operating system. Therefore it 
is possible to connect only devices which "rattle" the line 
after every received byte (like the 520ST with RTS). The 
signal goes to input 12 of the MFP, but unfortunately is 
tested only for the signal edge. You will not have any luck 
connecting a printer because they usually hold the CTS 
signal high as long as the buffer is not full. There is no 
signal edge after each byte, which means that only the 
first byte of a text is transmitted, and then nothing. 
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# - SEND 
Signal ground. 
8 DCD 


Carrier signal detected. This line, which goes to interrupt 
input I1 of the MFP, is normally serviced by a modem, 
which tells the computer that connection has been made 
with the other party. 


20 DTR 
Device ready. This line signals to a device that the 
computer is turned on and the interface will be serviced as 
required. It comes from I/O port A bit 4 of the sound 
chip. 


22° ca 
Ring indicator is a rather important interrupt on I6 of the 
MFP and is used by a modem to tell the computer that 
another party wishes connection, that is, someone called. 


| 
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Figure 2.4-1 RS-232 Connection 
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2.5 The MIDI Connections 


The term MIDI is probably unknown to many of you. It 1s an abbreviation 
and stands for Musical Instrument Digital Interface, an interface for musica] 
instruments. - 


It is certainly clear that we can't simply hook up a flute to this port. So first 
a little history. Music professionals (more precisely: keyboardists, 
musicians who play the synthesizer) demanded agreement between the 
various manufacturers to interface computers to musical instruments. They 
found it absurd to connect complicated set-ups with masses of wire. The 
idea was to service several synthesizers from one keyboard. 


The tone created was basically analog (and still is, to a degree), so that the 
manufacturers agreed that a control voltage difference of 1V corresponded 
to a difference in tone of 1 octave. This way one could play several devices 
under "remote control," but not service them. 


This changed substantially when the change was made to digital tone 
creation. Here one didn't have to turn a bunch of knobs, there were buttons 
to press, whereby the basis for digital control was created. 


Some manufacturers got together and designed a digital interface, the basic 
commands of which would be the same throughout, but which would still 
Support the additional features of a given device. 


The device is based on the teletype, the current-loop principle, which is not 
very Susceptible to noise, but significantly faster. The transfer rate is 31250 
baud (bits per second). The data format is set at one start bit, eight data bits, 
and one stop bit. 


An IC can therefore be used for control which would otherwise be used for 
RS-232 purposes. You see the connection to the system in figure 2.5-1. 


Logically, MIDI is multi-channel System, meaning that 16 devices can be 
serviced by one master, or a device with 16 voices. These devices are all 
connected to the same line (bus principle). To identify which device or 
which voice is intended, each data packet is preceded by the channel 
number. The device which recognizes this number as its own then executes 


the desired action. 
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You may wonder what such an interface is doing in a computer. A computer 
can provide an entire arsenal of synthesizers with settings or complete 
melodies (sequencer) because of its high speed and memory capacity. It can 
also be used to record and store input from a synthesizer keyboard. 


For this purpose the ST has the interfaces MIDI-IN and MIDI-OUT. The 
interfaces are even supported by the XBIOS so you don't have to worry 
about their actual operation. | 


The current loop travels on pins 4 and 5, out through pin 4 (4+) of 
MIDI-OUT and in at 5, when a device is connected. 


For MIDLIN the situation is reversed because the current flows in through — 
pin 4 and back out through pin 5. It goes though something called an 
optocoupler which electrically isolates the computer from the sender. 


The received data are looped back to MIDI-OUT (pins 1 and 3), which 


implements the MIDI-THRU function, although not entirely according to 
the standard. 
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Figure 2.5-1 MIDI System Connection 
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2.6 The Cartridge Slot 


The cartridge slot can be used exclusively for inserting ROM cartridges. Up 
to 128K in the address space $F A0000 to $F BFFFF can be addressed. The 
reason we stressed the exclusivity of the read access is the following. We 
thought it would be practical to outfit a cartridge with RAM and then load 
programs into it after the system start which would still remain after a reset. 
In order to try this we brought the R/-W signal to the outside. The 
experience taught us, however, that a write access to these addresses creates 
a bus error. The GLUE takes care of this. As you see, nothing is left to 

chance in the Atari. : 


Figure 2.6-1 The Cartridge Slot 


1 = +5VDC 2 Address 8 

2 = +5VDC 224 Address 14 

3 = Data 14 23 = Address 7 

4 = Data i 24 = Address 9 

5 = Data ae a Address 6 
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7 = Data 10 27 = Address 2 
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2.6.1 ROM Cartridges 


We want to spend this section telling you how a program is put into ROM, 
as well as how the operating system recognizes and loads such a program. 


These cartridges are technically feasible, since many manufacturers are now 
making ROM cartridge boards and programming devices for the ST 
computers. 


The most important aspect is the first longword in ROM, which must 
contain an index number, or "magic number". This is read when the system 
Start occurs—it checks to see whether there is a program cartridge or a 
diagnostic cartridge plugged into the cartridge port. The former must 
contain the index number $ABCDEF42, the latter the index number 
$FA52255F. 


We wouldn't want to go any farther with the diagnostic cartridge. It should 
be enough that the operating system jumps to immediately test the address 
$FA0004 without initializing GEMDOS. You won't get any system 
processes anyway from this cartridge. 


The program cartridges are what interest us. We can call up several 
programs from a ROM module of this type. Every program must have an 
introductory section, or application header, to be started by the operating 
. system. The first must begin right after the magic number (from $FA0004), 
and must be made up of the following: 


1 longword: 
Address of the next header, when multiple programs reside in one cartridge. 
The header of the last (or only) program must contain $00000000. 


1 longword: 

Initialization code. This is where GEMDOS gets information, first about the 
handling of the program. In particular, this longword is made up of an 
address which points to the initialization routine (when needed). The most 
significant byte in this longword states at which point in time this routine 
Should jump. 
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This is arranged as follows: 


BIT 

Q The routine will be executed before the interrupt vectors, 
video RAM, etc., 1s installed. 

1 The routine will be executed before GEMDOS is initialized. 

3 The routine will be executed before GEMDOS is loaded. 
NOTE: This function is not accessible to computers which 
have GEMDOS in ROM! 

5S Character which indicates that the program should be handled 
as an accessory. 

6 Character which identifies the program as a .TOS type, and 
not requiring the GEM system. 

7 Character which identifies the program as a .TTP type, and 
requiring starting parameters. 


1 longword: 
Starting address of the program, i.e. where it would start if you 
double-clicked it. 


1 word: 
Time in DOS format; has no meaning during runtime. 


1 word: 
Date in DOS format, see the previous entry. 


1 longword: 
Program length in bytes; has no meaning during runtime. 


String: 

Program name in explanatory text. The program name is inserted according 
to normal conventions, 1.e., up to 8 characters, a period (.), and three 
characters after the period. NOTE: The string absolutely must be concluded 
by $00. 


So, that's it. As for the rest: We've neglected to give you any information 
on clicking. Some program cartridges have their own icons, similar to a 
disk drive icon. Click this icon. It will show the programs contained in the 
cartridge; you may then start the desired program. 
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2./ The Floppy Disk Interface 


The interface for floppy disk drives is conspicuous because of the unusual 
connector, a 14-pin DIN connector. All of the signals required for the 
operation of two disk drives are available on it. 


You know most of the signals from the description of the disk controller 
1772, since nine of the available connections are connected to the controller 
either directly or through a buffer. Only the drive select 1 and drive select 2 
signals and the side 0 select are not derived from the disk controller. These 
signals come from port A of the sound chip. 


Pinout of the disk connector: 


1 READ DATA 8 MOTOR ON 

2; SIDE.°0: SELECT 9 DIRECTION<IN 
3 GND LOSSTEP 

4 INDEX lil WRITE DATA 

> DRIVE 0 oSEEECT 12 WRITE GATE 

6 DRIVE .1 SELECT 13 TRACK OO 

7 GND 14 WRITE PROTECT 
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Figure 2.7-1 Disk Connection 
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2.8 The DMA Interface 


This 19-pin jack can handle up to 8 DMA-compatible devices. These include 
hard disks, networks, and even coprocessors. The communications 
between the external devices and the ST run at a speed of up to 1 million 
bytes per second. 


1-8 DO0O-D7 
Bidirectional data lines 
9 CS 


10 


11 
12 


13 
14 


iS 
16 


17 
18 


19 


Chip Select, low-active. This line is activeated from the computer — 
when either commands are sent to the device, or status bytes are read 
from there. If DMA transfer is in process, the signal is in a wait state. 
IRQ 

Interrupt Request, low=active. This signal is produced by the device, 
and tells the computer that an action is done (e.g., DMA transfer). 
GND 

RST 

Reset, low=active. 

GND 

ACK. ~~ 

Acknowledge, low-active. This signal only has meaning during DMA 
transfer. This indicates the device to the computer's DMA controller, 
depending on the data direction, whether a byte is received from the 
device or whether a legal data byte lies on the bus. 

GND 

Al 

Address 1. This signal tells the device's DMA controller whether the 
device address is set on bus with all commands (A1=low) or whether 
parameter bytes are handled (usually 5 parameter bytes; Al=high). 
GND 


R/W 

Read/Write. This line also controls the controller, and is valid only 
when initializing. Write(=low): Command bytes snet; Read (=high): 
Waiting for a status byte. 

DRQ 

Data Request, low=active. This signal is produced from the device 
only during DMA transfer, depending upon data direction, when it can 
receive a byte from the controller; or otherwise, set a byte on the bus. 


Abacus Software Atari ST Internals 


There are two different methods of transfer. One is a computer controlled 
data transfer using the Al, CS and R/W lines. The other transfer of data, 
controlled from the device itself (the DMA transfer), runs without the 
computer with the help of the DRQ and ACK lines. 


A connection can be seen between the chip description of the DMA 


controller, and the reset routine in the operating system, which checks for 
all eight possible DMA devices. 


Figure 2.8-1 DMA Port 
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Figure 2.8-2 DMA Connections 
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Chapter 3 


The ST Operating System | 


The GEMDOS 

Memory, files and processes 

The BIOS Functions 

The XBIOS 

The Graphics 

An overview of the line-A variables 
Examples for using the line-A opcodes 
The Exception Vectors 

The line-F emulator 

The interrupt structure of the ST 
The ST VT5S2 Emulator 

The ST System Variables 

The 68000 Instruction Set 
Addressing modes | 

The instructions 

The BIOS listing 
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The ST Operating System 


GEMDOS--what is it? Is it in the ST? The operating system is supposed to 
be TOS, though. Or is it CP/M 68K? Or what? 


These questions can be answered with few words. The operating system in 
the ST is named TOS--Tramiel Operating System--after the head of Atari. 
This TOS, in contrast to earlier information has nothing to do with CP/M 
68K from Digital Research. At the start of development of the ST, CP/M 
68K was implemented on it, but this was later changed because CP/M 68K 
is not exactly a model of speed and efficiency. A 68000 running at 8MHz 
and provided with DMA would be slowed considerably by the operating 
system. 


At the beginning of 1985, Digital Research began developing a new 
operating system for 68000 computers, which would include a user-level 
interface. This operating system was named GEMDOS. It is exactly this 
GEMDOS which makes up the hardware-independent part of TOS. Like 
CP/M, TOS consists of a hardware-dependent and a hardware-independent 
part. The hardware-dependent part is the BIOS and the XBIOS, while the 
hardware-independent part is called GEMDOS. A large number of functions 
are built into GEMDOS, through which the programmer can control the 
actual input/output functions of the computer. Functions for keyboard input, 
text output on the screen or printer, and the operation of the various other 
interfaces are all present. Another quite important group contains the 
functions for file handling and for logical file and disk management. 
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3.1 The GEMDOS 


When you look at the functions available under GEMDOS, you will 


eventually come to the conclusion that the whole thing is not really new. All 


the functions in GEMDOS are very similar to the functions of the MS-DOS 
operating system. Even the functions numbers used correspond to those of 
MS-DOS. But not all MS-DOS functions are implemented in GEMDOS. 
Especially in the area of file management, only the UNIX compatible 
functions are implemented in GEMDOS. The "old" block-oriented 
functions which are included in MS-DOS to maintain compatibility with — 
CP/M are missing from GEMDOS. Also, special functions relating to th 
hardware of MS-DOS computers (8088 processor) are missing. 


Another essential difference between MS-DOS and GEMDOS is that for 
GEMDOS calls as well as for the BIOS and XBIOS, the function number, 
the number of the desired GEMDOS routine, and the required parameters 
are placed on the stack and are not passed in the registers. The 68000 is 
particularly suited to this type of parameters passing. GEMDOS is called 
with trap #1 and the function is executed according to the contents of 
the parameter list. After the call, the programmer must put the stack back in 
order himself, by clearing the parameters from memory. 


The basic call of GEMDOS functions differs from the BIOS and XBIOS 
calls only in the trap number. 


In regard to all GEMDOS calls, it must be noted that registers DO and AO 
are changed in all cases. If a value is returned, it is returned in DO, or DO 
may contain an error number, and after the call AO (usually) points to the 
Stack address of the function number. Any parameters required in DO or AO 
must be placed there before GEMDOS is called. 


The remainder of this section describes the individual] GEMDOS functions. 
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$00 TERM 


C: void Pterm0 () 


Calling GEMDOS with function number O ends the running program and 
returns to the program from which it was started. For applications 
(programs started from the desktop), control is returned to the desktop. If 
the program was called from a different program, control is passed back to 
the calling program. This point is important for chaining program segments. 


clriw .=(6p) 
trap #1 
$01 CONIN 


Cf wong Ceonsn () 


CONIN gets a single character from the keyboard. The routine waits until a 
character is available. The character read from the keyboard is returned in 
the DO register. The ASCII code of the pressed key is returned in the low 
byte of the low word, while the low byte of the high word of the register 
contains the scan code from the keyboard. This is important for reading 
keys which have no ASCII code, such as the 10 function keys or the editing 
keys. These keys return the ASCII value zero when pressed. 


The scan code can be used to determine if the keypad or the main keys were 
pressed. These keys have identical ASCII codes, but different scan codes. 


In addition, Shift status can be determined from the upper eight bits (bits 24 
to 31) by calling Cconin. In this case, bits 24-31 correspond to bits 0 to 7 in 
BIOS function 11 ("kbshift"). The information can only be sent on a Cconin 
call when bit 3 of the memory location "conterm" (address $484) is set. If 
this bit is unset, then the shift bits after Cconin are deleted. | 


Cconin does not recognize <Control><C>. 


move.w #1,-(sp) Function number on the stack 
trap #1 Call GEMDOS 
addq.1 #2,sp Correct. stack 
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$02 CONOUT 


C: void Cconout (c) 
bot caer 


CONOUT, also known as Cconout, represents the Simplest and most 
primitive character output of GEMDOS. With this function only one 
character is printed on the screen. The character to be displayed is placed on 
the stack as the first word. The ASCII value of the character to be printed 
must be in the low byte of the word and the high byte should be zero. 


The character printed by CONOUT is sent to device number 2, the normal 
console output. Control characters and escape sequences are interpret 
normally. 


move.w #65,-—(sp) Output. an. A 
move.w #2,-(sp) CONOUT 

Exap #1 Call GEMDOS 
addq.1l #4,sp Correct stack 


——___----_—— 


$03 AUXILIARY INPUT 


Cs. 2 ‘Caix isi} 


The RS-232 interface of the ST goes under the designation "auxiliary port” 
A character can be read from the interface with the Cauxin function. The 
function returns when a character has been completely received. The 
character is returned in the lower eight bits of register DO. 


move.w #3,-(sp) Cauxin 
ee a= 5 2, #1 Call GEMDOS, output character 
addq.1l #2,sp Correct stack 


Character in DO 


eee 
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$04 AUXILIARY OUTPUT 


Ci MOLE, Carxour (c) 
Ant 3s: 


A character can be transmitted over the serial interface, similar to the input 
of characters. With this function the programmer should clear the upper 
eight bits of the word and pass the character to be sent in the lower eight 
bits. 


move.w #$41,-(sp) An A should be output 
move.w #4,-(sp) Cauxout 
trap #1 Call GEMDOS, output character 


addq.1 #4,sp Correct stack 


$05 PRINTER OUTPUT 


Cr avoid: Cpornout tc) 
LNE: CF 


PRINTER OUTPUT is the simplest method of operating a printer connected 
to the Centronics interface. One character is printed with each call. 


An important part of PRINTER OUTPUT is the return value in DO. If the 
character was sent to the printer, the value -1 ($FFFFFFFF) is returned in 
DO. If, after 30 seconds, the printer was unable to accept the character (not 
turned on, OFF LINE, no paper, etc.), GEMDOS returns a time out to the 
program. DO then contains a zero. 


move.w #65,-—(sp) Output an A 

move.w #5,-(sp) Function number 

trap #1 Call GEMDOS, output character 
addq.1 #4,sp Correct stack 

tst.w DO Affect flags 

beg printererror 


109 


Abacus Software Atari ST Internals 


eee 


$06 RAWCONIO 


C: long Crawio(c) 
Int cs 


-RAWCONIO is a somewhat unusual mixture of keyboard input and screen 
output; it also receives a parameter on the stack. | 


The keyboard is tested with a function value of $FF. If a character is 
present, the ASCII code and scan code are passed to DO as described for 
CONIN. If no key value is present, the value zero is passed as both the 
ASCII code and the scan code in DO. The call to RAWCONIO with 

parameter $FF is comparable to the BASIC IN KEY$ function. 7 


If a value other than $FF is passed to the function, the value is interpreted as 
a character to be printed and it is output at the current cursor position. This 
output also interprets the control characters and escape sequences properly. 


SLART + 
move.w #Sff£,-(sp) Function value test keyboard 
move.w #6,—-(sp) Function number 

trap #1 Call GEMDOS, test keyboard 
addq.1l #4,sp Correct stack 

LSU sw DO Character arrived? 

beq START Not yet 

cmp.b #3,D0 “C selected as the end marker 
beq END 

move DO,-(sp) Character for output on the stack 
move #6,—-(sp) Function number 

Crap #1 Call GEMDOS, test keyboard 
addq.1l #4,sp Correct stack 

bra START Get new character 


eee 


$07 DIRECT CONIN WITHOUT ECHO 


C: long Crawcin() 


The function $07 differs from $01 only in that the character received from 
the keyboard is not displayed on the screen. It waits for a key just as does 
CONIN. 
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move.w #8,-(Ssp) Cauxin 
trap #1 Call GEMDOS, output character 
addq.1 #2,sp Adjust stack 


Character in DO 


$08 CONIN WITHOUT ECHO 


Cc: long Cnecin() 


Both function $08 and function $07 have exactly the same effect. The 
reason for this seemingly nonsensical behavior lies in the abovementioned 
compatibility to MS-DOS. Under MS-DOS these two functions are different 
in that with $08, certain keys not present on the ATARI are evaluated 
correctly, while this evaluation does not take place with function $07. 


move.w #8,-(sp) Cauxin 
trap #1 Call GEMDOS, output character 


addq.1 #2,sp Adjust stack 
: Character in DO 


$09 PRINT LINE 


Cz VWoid.-Ccoonws (c) 
int <c; 


You are already familiar with functions that output individual characters on 

the screen (see CONOUT and RAWCONIO). PRINT LINE offers you an 

easy way to output text. An entire string can be printed at the current cursor 

position with this function. To do this, the address of the string is placed on 

the stack as a parameter. The string itself.is concluded with a zero byte. 

—— sequences and control characters can also be displayed with this 
unction. 


After the call, DO contains the number of characters which were printed. 
The length of the string is not limited. 
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move.l #text,-(sp) Address of the string on the stack 
move #509,-(sp) Function number PRT LINE 

trap #1 Call GEMDOS 

addq.1 #6,sp Clear the stack 

text .dc.b "This is the string to be printed'’,$0D,S$0A,0 


$0A READLINE 


Cea VOLE Coones (but) 
ehar “but; 


READLINE is a very easy-to-use function for reading characters from the 
keyboard. In contrast to the "simpler" character-oriented input functions, an 
entire input line can be taken from the keyboard with READLINE. The 
characters entered are displayed on the screen at the same time. 


The address of an input buffer is passed to the function as the parameter. 
The value of the first byte of the input buffer determines the maximum 
length of the input line and must be initialized before the call. At the end of 
the routine, the second byte of the buffer contains the number of characters 
entered. The characters themselves start with the third byte. 


The routine used by READLINE for keyboard input is quite different from 
the character-oriented console inputs. Escape sequences are not interpreted 
during the output. Only control characters like <Control><H> (backspace) 
and <Control><I> (TAB) are recognized and handled appropriately. The 
following control characters are possible: 


“C Ends input and program (!) 

“H Backspace one position 

oe TAB 

“J Linefeed, end input 

"M ‘CR, end anput 

“R Entered line is printed in new line 
“U. ‘Don't Count Line, ~steect: new. lane 

“X Clear line, cursor at start of line 


A function like *H (deleting a character entered) is useful, but for large 
programs you should write your own input routine because “C is very 
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"dangerous." Unlike CP/M, the program will be ended even if the cursor is 
not at the very start of the input line. 


If more characters are entered than were indicated in the first byte of the 
buffer at the initialization, the input is automatically terminated. If the input 
is terminated by ENTER, “J, or “4M, the terminating character will not be 
put in the buffer. 


After the input, DO contains the number of characters entered, excluding 
ENTER, which can be found at buffer+1. 


pea buffer Address of the input buffer 

move #S0A,-(sp) Function number 

trap #1 

addq.1l #6, (sp) Make room on stack 

butler 2dc.b “20 We want a maximum of 20 characters 
ac: b: v Number of given characters 
as. 20 of the input buffer 


$0B CONSTAT 


C2 ne CCOnsS 4) 


All key presses are first stored in a buffer in the operating system. This 
buffer is 64 bytes in length. The key values stored there are taken from the 
buffer when a call toa GEMDOS output routine is made. 


CONSTAT can be used to check if characters are stored in the keyboard 
buffer. After the call, DO contains the value zero or $FFFF. A zero in DO 
indicates that no characters are available. 


EEStCLOOp? 

move #50B,-(sp) Function number 
trap #1 

addq.1 #2, (sp) Make room on stack 
tst.w DO Character available? 
beq testloop NO, then look again 
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$0E SETDRV 


C: long Dsetdrv (drv) 
int drv; 


The current drive can be set with the function SETDRV. A 16-bit parameter 
containing the drive specification is passed to the routine. Drive A is 
addressed with the number 0 and drive B with the number 1. 


After the call, DO contains the number of the drive active before the call. 


move #32,-(sp) Drive C, e.g. RAMdisk 
move #50E,-(sp) Function number 

trap #1 

addq.1l #4, (sp) Make room on stack 


: Previous current drive in DO 
eee 
$10 CONOUT STAT 


Cy tnt. -Coonos it) 


CONOUT STAT returns the console status in DO. If the value $FFFF is 
returned, a character can be displayed on the screen. If the returned value is 
zero, no Character output is possible on the screen at that time. Incidentally, 
all attempts failed at creating a not-ready status at the console. The only 
imaginable possibility for the not-ready status would be if the output of the 
individual bit pattern of a character was interrupted and the interrupt routine 
itself tried to output a character. This case could not, however, be created. 


move #510,-(sp) Function number 
trap #1 
addq.1 #2, (sp) Make room on stack 


Always $FFFF in DO 


a eeeeeeeeeeeeeeeNeSFSsSesesese 
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$11 PRTOUT STAT 


Cs ant Cpormes() 


This function returns the status, the condition of the Centronics interface. If 
no printer is connected (or turned off, or off line), DO contains the value 
zero after the call to indicate printer not available." If, however, the printer 
is ready to receive, DO contains the value $FFFF. 


move #S511,-(sp) How's the printer doing? 
trap # 1 

addq.1 #2, (sp) Make room on the stack 
tst do 

beq printererror Go here if not ready 


$12 AUXIN STAT 


Cr 12nt Cauxzis (co) 


AUXIN STAT shows whether a character is available from the serial 
interface receiver ($FFFF) or not ($0000). The value is returned in DO. 


waitloop: 

move #S12,-(sp) We wait for a character 
trap # 1 from the serial interface 
addq.1 #2, (sp) Make room on the stack 

cSt do Is there a character there? 
bne waitloop No, not yet 


$13 AUXOUT STAT 


Ci 3nt: Cauxros{) 


AUXOUT STAT gives information about the state of the serial bus. A value 
of $FFFF indicates that the serial interface can send a character, while zero 
indicates that no characters can be sent at this time. 
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waitloop: 

move #513,-(sp) Wait for a character 
trap # 1 from the serial interface 
addq.1l #2, (sp) Make room on the stack 
ESt do Received one yet? 

‘bne waitloop No, not yet 


TT ees 


$19 CURRENT DISK 


Cs. 2net: Doetdrvy( 


For many applications it is necessary to know which drive is currently 
active. The current drive can be determined by the function $19. After the 
call, DO contains the number of the drive. The significance of the drive 
numbers is the same as for $0E, SET DRIVE (O=A, 1=B). 


move #519,-(sp) Which drive is active? 
trap # 1 It will be sent over 
the serial interface 
aAgdG «1. #2..( sr) Make room on the stack 
ADD DO; 723 There will now be a character in 


DO between 'A’ and 'p! 


OT eeeeeeseseseSC=*®T 


$1A SET DISK TRANSFER ADDRESS 


C: void Fsetdta (buf) 
Char *buf; 


The disk transfer address is the address of a 44-byte buffer required for 
various disk operations (especially directory operations). Along with the 
GEMDOS functions SEARCH FIRST and SEARCH NEXT are examples 
for using the DTA. 


move.l #DTADDRESS, — (sp) Address of the 44-byte DTA buffer 


move.w #$la,-(sp) Function number SET DTA 
trap #1 Set DTA 
addq.1l #6,sp Clean up the stack 


eee 
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$20 SUPER 


This function is especially interesting for programmers who want to access 
the peripherals or system variables available only in the supervisor mode 
while running a program in the user mode. After calling this function from 
user mode, the 68000 is placed in the supervisor mode. In contrast to the 
XBIOS routine for enabling the supervisor mode, additional GEMDOS, 
BIOS, and XBIOS calls can be made after a successful SUPER call. 


Calling the SUPER function with a value of -1L ($FFFFFFFF) tells us the 
processor's current operating mode. If the result in DO after the call is 0, 
the processor is in user mode. A value of $0001 signifies that the processor 
is in Supervisor mode. Switching modes is not carried out yet. 


A program in user mode can call the SUPER function with a zero on the 
stack. In this case, the supervisor mode will be turned on. The supervisor 
Stack pointer points to the current value of the user stack, and the original 
value of the supervisor stack is in DO. This value must be stored in the 
program to later return to the user mode. If the change to user mode is not 
made before the end of the program, the odds of a system crash are good. 


If a value other than zero is passed to the SUPER function the first time it is 
called, this value is interpreted as the desired value of the supervisor stack 
pointer. In this case as well, DO contains the original value of the supervisor 
stack pointer, which the program should save. 


As mentioned above, the user mode should be reenabled before the end of 
the program. This change of modes requires setting the address used by the 
Supervisor stack pointer back to its original value. 


The SUPER function differs from all other GEMDOS functions in one very 
important respect. Under certain circumstances, this call can also change the 
contents of Al and D1. If you store important values in these registers, you 
must save the values somewhere before calling the SUPER function. 


The 68000 is in the user mode 


Slr sae )t =e) User stack becomes supervisor stack 
move.w #$20,-(sp) Call SUPER 

trap #1 Supervisor mode is active after TRAP 
add.l #6,sp DO = old supervisor stack 


move.l1 d0, SAVE SSP Save value 


Here processing can be done in the supervisor mode 
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move.l SAVE SSP,-(sp) Old supervisor stack pointer 
1] move.w #$20,-(sp) Call SUPER 
HH trap #1 Now we are back in the user mode 


add.l +#6,sp 


$2A GET DATE 


C: int Tgetdate () 


You have no doubt experimented with the status field at one time or anothe— 
Among other functions, the status field contains a clock with time and date. 
It can be useful for some applications to have that data available. The date 
can be easily determined by GET DATE. This call requires no parameters 
and puts the date in the low word of register DO. It is thoroughly encoded, 
though, so the result in DO must be prepared to get the correct date. 


The day in the range 1 to 31 is coded in the lower five bits. Bits 5 to 8 
contain the month in the range 1 to 12, and the year is contained in bits 9 to 
15. The range of these "year bits" goes from 0 to 119. The value of these 
bits must be added to the value 1980 to get the actual year. The date 
12/12/1992, for example, would be %0001100.1100.01100 in binary, or 
$198C in DO. The lengths of the three fields are marked with periods. 


move #52a,—(sp) We want to get some data =e 
| trap #1 
| addq.1 #2, (sp) 
| move d0,dl Store result in Dl for now 
and #311111,D0 Mask the day bits and 
| move d0Q,DAY store them 
LSR #5,dl Shift the 5 day bits 
| move d1,do 
| and #$1111,d0 and mask the month bits 
move DO,MONTH Store the month number 
# LSR #4,al Shift the month bits 
i move dl1,YEAR Year is in Dl 
DAY ds.w i 
MONTH ds.w 1 
YEAR ds.w L 
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¢2B SET DATE 


c: int Tsetdate (date) 
int. date; 


The clock time and date can also be set from application programs. This 1s 
particularly interesting for programs which use the date and/or clock time. 
An example of this would be invoice processing in which the current date is 
‘nserted in the invoice. Such programs can then ask the user to enter the 
date. This avoids the problems that occur if the user forgets to set the date 
and clock time on the status field beforehand. 


The date must be passed to the function SET DATE in the same format as it 
is received from GET DATE, bits 0-4 = day, bits 5-8 = month, bits 9-15 = 
year-1980. 


move.w #%101101011001,- (sp) Set date to 10/25/1985 


move.w #$2b,-(sp) Function number of SET DATE 
txap #1 Set date 
addq.1l #4,sp Repair stack 


$2C GET TIME 
C: int Tgettime () 


The function GET TIME returns the current (read: set) time from the 
GEMDOS clock. Similar to the date, the clock time is coded in a special 
pattern in individual bits of the register DO after the call. The seconds are 
represented in bits 0-4. But since only values from O to 31 can be 
represented in 5 bits, the internal clock runs in two second increments. In 
order to get the correct seconds-result the contents of these five bits must be 
multiplied by two. The number of minutes is contained in bits 5 to 10, while 
the remaining bits 11-15 give information about the hour in 24-hour format. 


Waitloop: 

move R220; — (Sp) Is.1t noon yet? 

trap #1 Get the time from GEMDOS 
addq.1 #2,sp 

move a0, dl Store result in Dl 
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and FOLLY DO Store seconds in steps 
move DO, SEC of two 

LSR #4,D1 Shift 4 second bits 
bne waitloop No, not yet 


$2D SET TIME 


C: int Tsettime (time) 
int time; 


It is also possible to set the clock time under GEMDOS. The function SE™ 
TIME expects a 16-bit value (word) on the stack, in which the time is codeu 
in the same form as that in which GET TIME returns the clock time. 


When GEMDOS has the given time, DO returns the value 0; otherwise the 
value returned is $FFFFFFFF. GEMDOS handles time much as it does the 
date. Time changes through GEMDOS cannot be conveyed through the 
XBIOS. Select either XBIOS or GEMDOS. If you cross the two, you will 
end up with some very unpleasant complications. 


move.w #%61000101010111101,-(sp) Clock-Limeo17+21258 
move.w #$2D,-(sp) Function # of GET TIME 
trap #1 Set date 

addq.1 #4,sp Repair stack 


$2F GET DTA 


C: long Fgetdta() 


The function $2F is the counterpart of SET DTA ($1A). A call to GET DTA 
returns the current disk transfer buffer address in DO. A description of this 
buffer is found with the functions SEARCH FIRST and SEARCH NEXT. 


move #S2£,-(sp) Function number Fgetdta 
trap #1 Get DTA 

a0gdGg ul: #2,sp 

move.l dQ,DTAPOINTER and mark for later 
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$30 GET VERSION NUMBER 


c: int Sversion () 


Calling this function returns in DO the version number of GEMDOS. In the 
version of GEMDOS currently in release, this question is always answered 
with $0D00, corresponding to version 13.00. Official Atari documentation 
claims that a value of $0100 should be returned for this version, though 
perhaps the value should indicate that the present GEMDOS version is the 
¢$D = diskette version. 


move #30,-(sp) Look to see which 

trap #1 version we have 

addq.1l #2,sp 

cmp #$1300,d0 The recognized version? 
bne not tos It can't be given 


$31 KEEP PROCESS 


C: void Ptermres (keepcnt, retcode) 
long keepcnt; 
int retcode; 


This function is comparable to the GEMDOS function TERM $00. The 
program is also ended after a call to this function. $31 does differ from $00 
in several important points. 


After processing TRAP #1, like TERM, control is passed back to the 
program which started the program just ended. In contrast to TERM, a 
termination condition can be communicated to the caller. While TERM 
returns the termination value zero (no error), zero or one may be selected as 
the termination value for $31. A value other than zero means that an error 
occurred during program processing. 


Another essential point lies in the memory management of GEMDOS. When 
a program is started, the entire available memory space 1s made available to 
it. If the program is ended with TERM, the memory space is released and 
made available to GEMDOS. The entire area of memory released 1s also 
cleared, filled with zeros. The program actually physically disappears from 
the memory. With function $31, however, an area of memory can be 
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protected at the start address of the program. This memory area is not 
released when the program is ended and it is also not cleared. The program 
could be restarted without having to load it in again. 


Practical applications for Ptermres() are spoolers, RAM disks and other 
utilities which are installed once and remain in memory for storage or 
processing. At the same time, such programs must be ended correctly after 
installation to allow other programs to be loaded and started. 


KEEP PROCESS is called with two parameters. The example program 
shows the parameter passing. It is also important that memory additionally 
reserved for programs be Malloc not be freed up. If files are opened by 
Ptermres() at that time, these will be closed by GEMDOS. 


move.w #0,-(sp) Error code no error, else 1 
move.l1 #$31000,-(sp) Protect $1000 bytes at program start 
move.w #5$31,-(sp) Function number, end program 


trap #1 2 eon OW 
2 This time, don't clear the stack! 


$36 GET DISK FREE SPACE 


C: void Dfree (buffer, drive) 
long *buffer 
int drive 


It can be very important for disk-oriented programs to determine the amount 
of free space on the diskette, then warn the user to change disks. "Disk 
full" messages or even data loss can then be avoided. 


Function $36, Dfree(), returns this information. The number of the desired 
disk drive and the address of a 16-byte buffer must be passed to the 
function. If the value 0 is passed as the drive number, the information is 
fetched from the active drive, a 1 takes the information from drive A, and a 
2 from drive B. 


The information passed in the buffer is divided into four longwords. The 


first longword contains the number of free allocation units. Each file, even 
if it is only eight bytes long, requires at least one such allocation unit. 
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The second longword gives information about the number of allocation 
units present on the disk, regardless of whether they are already used or are 
still free. For the "small" single-sided diskettes this value is $15C or 351, 
while the double-sided disks have $2C7 = 711 allocation units. 


The third longword contains the size of a disk sector in bytes. For the Atari 
this is always 512 bytes ($200 bytes). 


The last longword is the number of physical sectors belonging to an 
allocation unit. This is normally 2. Two sectors form one allocation unit. 


The amount of free disk space can be easily calculated from this data. 


move.w #0,-(sp) Information from the active drive 
pea BUFFER Address of the 16-byte buffer 
move #536,—-(Sp) Function number 

trap #1 

addq.1l #6,sp Clean up stack 

BUFFER: 

freal: .ds.l 1 Free allocation units 

Coca. ~Cs. 2 ‘i fOta.. a110CaLLon- unics 

Dps: ay Fs gam Nd Bytes/physical sector 

pSpal:” .as. 1 1 Phys. sectors/alloc. unit 
$39 MKDIR 


C: int Dcreate (path) 
char *path; 


A subdirectory can be created from the desktop with the menu option "NEW 
FOLDER". Such a subdirectory can also be created from an application 
program with a call to $39. 


In order to create a new folder, the function $39 is given the address of the 
folder name, also called the pathname. This name may consist of 8 
characters and a three-character extension. The same limitations apply to 
pathnames as do to filenames. The pathname must be terminated with a zero 
byte when calling MKDIR. 
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After the call, DO indicates whether the operation was performed 
successfully. If DO contains a zero, the call was successful. Errors are 
indicated through a negative number in DO. At the end of this chapter you 
will find an overview of all of the error messages occurring in connection 
with GEMDOS functions. 


-move.l pathname Address of the pathname 
move #$39,-(sp) Function number 

trap #1 

addq.l #6,sp Repair stack 

Cst.w day Error occurred? 

bne error Apparently 

pathname: 


.dc.b ‘'private.dat'’,0 


$3A RMDIR 


C: int Ddelete (path) 
char “path; 


A subdirectory created with MKDIR can be removed with $3A. As before, 
the pathname, terminated with a zero, is passed to RMDIR. The error 
messages also correspond to those for MKDIR, with zero for success or a 
negative value for errors. An important error message should be mentioned 
at this point. It is the message -36 (SFFFFFFCA). This is the error message — 
you get when the subdirectory you are trying to remove contains files. 


Only empty subdirectories can be removed with RMDIR. If you get an 
error, erase directory files with UNLINK ($41), then call RMDIR again. 


pea pathname Address of the pathname 
move.w #$3A,-(sp) Function # 

trap #1 

addq.l #6,sp Repair stack 

CS. DO Is there an error? 
bne era sub dir It appears that way 
pathname: 


sOCcb... Empl i les a 270 
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$3B CHDIR 


C: int Dsetpath (path) 
char. *path; 


The system of subdirectories available under GEMDOS is exactly the same 
form available under UNIX. This system is now running on systems with 
diskette drives, but its advantages become noticeable first when a large mass 
Storage device such as a hard disk with several megabytes of storage 
Capacity is connected to the system. After a while, most of the time would 
probably be spent looking for files in the directory. 


To better organize the data, subdirectories can be placed within 
subdirectories. It can therefore become necessary to specify several 
subdirectories until one has the directory in which the desired file is stored. 
An example might be: 


\hugos.dat\criles.s\csorts .s\cqsort s 


Translated this would mean: load the file cqsort .s from the subdirectory 
csorts.s. This subdirectory csorts.s is found in the subdirectory 
cfiles.s, which in turn 1s a subdirectory of hugos.dat. If the whole 
expression is given as a filename, the desired file will actually be loaded 
(assuming that the file and all of the subdirectories are present). If you want 
to access another file via the same path (do you understand the term 
pathname?), the entire path must be entered again. But you can also make 
the subdirectory specified in the path into the current directory, by calling 
CHDIR with the specification of the desired path. After this, all of the files 
in the selected subdirectory can be accessed just by the filenames. The path 
is set by the function. 


move.l path,-(sp) Address of the path 

move.w #S$3b,-(sp) Function number 

trap #1 

addq.l #6,sp Repair stack 

tst.w. do Error occurred? 

bne error Apparently 

path: 

<dc.b "| \hugos:dat\cfiles.s\csorts.s\cqsort..s",0 
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$3C CREATE 


C: int Fcreate (fname, attr) 
char *fname; 
int attr; 


In all operating systems, the files are accessed through the sequence of 
opening the file, accessing the data (reading or writing), and then closing 
the file. This "trinity" also exists under GEMDOS, although there is an 
exception. Under CP/M, for example, a non-existent file can also be 
opened. When a file which does not exist is opened, it is created. Under 
GEMDOS, the file must first be created. The call $3C, CREATE, is used 
for this purpose. Two parameters are passed to this GEMDOS function: the 
address of the desired filename, and an attribute word. 


If a zero is passed as the attribute word, a normal file is created, a file which 
can be written to as well as read from. If the value 1 is passed as the 
attribute the file will only be able to be read after it is closed. This is a type 
of software write-protect (which naturally cannot prevent the file from 
disappearing if the disk is formatted). 


Other possible attributes are $02, $04, and $08. Attribute $02 creates a 
"hidden" file and attribute $04 a "hidden" system file. Attribute $08 creates 
a file with a "volume label." The volume label is the (optional) name which 
a disk can be given when it is formatted. The disk name is then created from 
the maximum of 11 characters in the name and the extension. Files with one 
of the last three attributes are excluded from the normal directory search in 
the Desktop. On the ST, however, they appear in the directory, e.g. as 
COMMAND.PRG. 


When the function CREATE is ended, a file descriptor, also called a file 
handle, is returned in DO. All additional accesses to the file take place over 
this file handle (a numerical value between 6 and 45). The handle must be 
given when reading, writing, or closing files. A total of $28 = 40 files can 
be opened at the same time. | 


If CREATE is called and a file with this name already exists, it is cut off at 
zero length. This is equivalent to the sequence delete the old file and create a 
new file with the same name, but it goes much faster. 


If after calling CREATE you get a handle number back in D0, the file need 
not be opened again with $3D OPEN. 
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move.w #50, -(sp) File should have R/W status 

pea filename Address of the filename on stack 
move.w #$3c,- (sp) Fcreate function number 

trap #1 Call GEMDOS 

addq.l #8,sp Clean up stack 

cSt do EEror occurred: 

bmi error It appears so 

move d0Q,handle Save file handle for later access 
filename: Don't forget the zero byte 


SOC 7D..- 7 Myla le. dat *70 


handle: 
<ascw. “1 


$3D OPEN 


C: int Fopen (fname, mode) 
Char *fname; 
int mode; 


You can only create new files with CREATE, or shorten existing files to 
zero length. But you must be able to process existing files further as well. 
To do this, such files must be opened with the OPEN function. 


The first parameter of the OPEN function is the mode word. With a zero in 
the mode word, the opened file can only be read, with one it can only be 
written. With a value of 2, the file can be read as well as written. The 
filename, ended with a zero byte, is passed as the second parameter. 


The OPEN function returns the handle number in DO as the result if the file 
is present and the desired access mode is possible. Otherwise DO contains 
an error number. See the end of the chapter for a list of the error numbers. 


Up until now, when we've discussed file functions, we have referred only 
to files. This is only half the story; devices can be opened and closed as well 
as files. These devices are the console (keyboard) and monitor, the serial 
port and the printer connection. See Chapter 3.1.1 for more information on 
GEMDOS and the file/device concept. We want to show you for now how a 
device is opened, and what handle to give it. This information is important 
insofar as device handles are different from file handles. 
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To open a device, the device name is given as a filename. The device names 
are: "CON:" for the console, "AUX:" for the serial interface and "PRN:" for 
the printer interface. After opening with the appropriate name, youll geta 
word-negative handle. $FFFF(-1) is returned for CON:, $FFFE(-2) is 
returned for AUX: and $FFFD(-3) is the handle for the printer port. 


move.w #$2,-(sp) File read and write 


pea filename Address of the filename on the stack 
move.w #$3d,-(sp) Function number 
trap #1 Call GEMDOS 
addq.1 #8,sp Clean up the stack 
CSt.. ao Error occurred? 
bmi error Apparently 
move d0,fhandle Save file handle for later accesses 
filename: Don't forget zero byte! 
SOC. 'myfile.dat',0 
handle: 
.ds.w 1 
$3E CLOSE 


C: int Fclose (handle) 

int handle; 
Every opened file should be closed when it is no longer needed within a ; 
program, or when the program itself is ended. Especially when writing, 
files must absolutely be closed before the program ends or data may be lost. 


Files are closed by the call CLOSE, to which the handle number is passed 
as a parameter. The return value will be zero if the file was closed correctly. 


move.w handle, -(sp) Handle number 
move.w #$3e,-(sp) Function number 
trap #1 Call GEMDOS 
addq.l #4,sp Error occurred? 
bmi error Apparently 
handle: 

.ads.w 1 
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ce it ce 
$3F READ 


C: long Fread(handle, count, buff) 
int handle; 
long count; 
Char “butt; 


Opening and closing files is naturally only half of the matter. Data must be 
Stored and the retrieved later. Reading such files can be done in a very 
elegant manner with the function READ. READ expects three parameters: 
first the address of a buffer in which the data is to be read, then the number 
of bytes to be read from the file, and finally the handle number of the file. 
This number you have (hopefully) saved from the previous OPEN. 


As return value, DO contains either an error number (hopefully not) or the 
number of bytes read without error. No message regarding the end of the 
file is returned. This is not necessary, however, since the size of the file is 
contained in the directory entry (see SEARCH FIRST/SEARCH NEXT). If 
the file is read past the logical end, no message is given. The reading will be 
interrupted at the end of the last occupied allocation unit of the file. The 
number of bytes read in this case is always divisible by $400. 


pea buffer Address of the data buffer 
move.l #$100,-(sp) Read 256 bytes 
move.w handle,-(sp) Space for the handle number 


move.w #S$3f,-(sp) Function number 
trap #1 
add ..1:. #12 ,sp 
CSt... “do Did an error occur 
bmi error Apparently 
cmp.l1 #$100,d0 256 bytes read? 
bne end of file Not enough data in file 
handle: 
6S .W >< Space for the handle number 
buffer: 
a8.D° $100 Suffices in our example 
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$40 WRITE 


C: long Fwrite(handle, count, buff) 
int handle; 
Long count: 
char *buff; 


Writing to a file is just as simple as reading from it. The parameters required 
are also the same as those required for reading. The file descriptors from 
OPEN and CREATE calls can be used as the handle, but the device 
numbers listed for READ can also be used. The output of a program can be 
sent to the screen, the printer, or in a file just by changing the handle 
number. 


pea buffer Address of the data buffer 
move.l #$100,-(sp) Read 256 bytes 
move.w handle,-(sp) Space for the handle number 


move.w #540,-(sp) WRITE request 
trap #1 
add.1l #12,sp 
Esousk. -<a0 Did an error occur? 
bmi error Apparently 
handle: 
saS.cw- UL Space for the handle number 
buffer: 
23.50 “S100 Suffices in our example 
$41 UNLINK 


C: int Fdelete (fname) 
char *fname; 


Files which are no longer needed can be deleted with UNLINK. To do this, 
the address of the filename or, if necessary, the complete pathname must be 
passed to the function. If the DO register contains a zero after the call, the 
file has been deleted. Otherwise DO will contain an error number. 
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pea fname Name of the file to be scratched 
move.w #S$41,-(sp) Function number Fdelete() 
trap #1 
add.l #6,sp 
Est.d. «a0 Did: an error occur? 
bmi error Apparently 
fname: 
Jace <b 'b: \hugos -dat\cfiles\csorts\cqsort.s'; 0 
$42 LSEEK 


C: long Fseek(offset, handle, seekmode) 
long offset; 
int handle; 
int seekmode; 


Up to now we have become acquainted only with sequential data accesses. 
We can read through any file from the beginning until we come the desired 
information. An internal file pointer which points to the next byte to be read 
goes along with each read. We can only move this pointer continuously in 
the direction of the end of file by reading. A few bytes forward or 
backward, setting the pointer as desired, 1s not something we can do. This 
is required for many applications, however. 


LSEEK offers an extraordinarily easy-to-use method of setting the file 
pointer to any desired byte within the file and to read or write at this 
point. This UNIX-compatible option of GEMDOS is much easier to use than 
the relative file management methods available under CP/M, for instance. 


A total of three parameters are passed to the LSEEK function. The first 
parameter specifies the number of bytes by which the pointer should be 
moved. An additional parameter is the handle number of the file. The last 
parameter is a mode word which describes how the file is to be moved. A 
zero aS the mode moves the pointer to the start of the file and from there the 
given number of bytes toward the end of the file. Only positive values may 
be used as the number. With a mode value of 1, the pointer is moved the 
desired positive or negative amount from the current position, and a 2 as the 
mode value means the distance specified is from the end of the file. Only 
negative values are allowed in this mode. 
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After the call, DO contains the absolute position of the pointer from the start 
of the file, or an error message. 


move.w #1,-(sp) Relative from the current file ptr 
move.w handle,-(sp) File handle 
move.l #$-20,-(sp) 32 bytes back 
move.w #542,-(sp) Function number 
trap #1 
add.1 #10,sp 
ESL. .d0 Did an error occur? 
bmi error Apparently 
handle: 
mo oem, Se Space for the handle number 


$43 CHANGE MODE (CHMOD) 


Ce 2nt. PMattrib(tname, Flag, attrib) 
char *fname; 
tnt. tLlag-: 
Int. -aActrip: 


With the CREATE function a file can be assigned a specific attribute. This 
attribute can be determined and subsequently changed only with the function 
CHANGE MODE. The name of the file must be known because the address 
of the name or the complete pathname must be passed to CHMOD. Another 
parameter word specifies whether the file attribute is to be read or set. 
Moreover, a word must be passed which contains the new attribute. When 
reading the attribute of a file this word is not necessary, but should be 
passed to the routine as a dummy value. We indicated the possible file 
attributes in our discussion of the function CREATE, but here they are again 
in a table: 


$00 = normal file status, read/write possible 
SO1l = File is READ ONLY 

$02 = "hidden" file 

$04 = system file 

$08 = file is a volume label, contains disk name 
910 = file is a subdirectory 

220 = file is written and closed correctly 


L3Z 
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$20 is given by the operating system, while the GEMDOS function MKDIR 
is used to create a subdirectory. The MKDIR function not only creates the 
directory entry with the appropriate attribute, it also physically arranges the 


subdirectory on the disk. 


After the call, DO will contain the current attribute value, which will be the 
new value after setting the attribute, or a negative error number. 


First example: 


move.w #1,-(sp) 
move.w #1,-(sp) 


pea pathname 
move.w #$43,-(sp) 
trap #1 

add.l1 #10,sp 
tst.w dd 

bmi error 
pathname: 


Give file READ ONLY attribute 
Set attribute identifier 

We also need the pathname 
Function number 


Did an error occur? 
Apparently 


Don't forget zero byte at end! 


-de.b. "kid lime. not, 0 


Second example: 


move.w #0,-(sp) 
move.w #0,-(sp) 


pea pathname 
move.w #543,-(sp) 
trap #1 

add.l #10,sp 
tst.w dd 

bmi error 
pathname: 


Dummy value, not actually required 
Read attribute 

and the pathname 

Function number 


Did an error occur? 
Apparently 


Don't forget zero byte at the end! 


c= whateami i" 70 


a ——————________._._  e 
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$45 DUP 


C: int Fdup(handle) 
int handie; 


As mentioned in connection with the functions READ and WRITE, the 
devices console, line printer and RS-232 are available to the programmer. 
This permits input and output to be redirected to these devices. One of the 
devices can be assigned a file handle number with the DUP function. After 
the call the next free handle number is returned. 


move.w STDH,-(sp) Parameter is standard handle number (0-5) 
move.w #$45,-(sp) Execute DUP 


trap #1 

addq.l #4,sp 

CSsta2 “dal =S 0; ~3/1 05 0 ‘are possible 

bmi DUPERR 

move d0,NSTDH Result is non standard handle 
number (6-45) 

$46 FORCE 


C: int Fforce(stdh,nonstdh) 
iit.’ stdh: 
int nonstdh; 


The FORCE function allows further manipulation of handle numbers. If in a 
program the console input and output are used exclusively via the READ 
and WRITE functions with the handle numbers 0 and 1, input or output can 
be redirected with a call to this function. Screen outputs are written to a file, 
inputs are not taken from the keyboard, but from a previously-opened file. 


move .w NSTDil, — (sp) Parameter iS non-standard handle 
move.w STDH,-(sp) Standard handle (0-5) 

move.w #$46,-(sp) Execute FORCE 

trap # 1 

addq.1 #6,sp 

Sti Me =3/ or, 0 are possible 

bne FORCE ERR 


re 
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$47 GETDIR 


C: void Dgetpath(buf, drive) 
char *buf; 
1H sof .Ve: 


A given subdirectory can be made into the current directory with the 
function $37. All file accesses with a pathname then run only in the set 
subdirectory. Under certain presumptions it can be possible to determine the 
pathname to the current subdirectory. This is accomplished by the function 
call GETDIR, $47. This call requires the designation of the desired disk 
drive (O=current drive, 1=drive A, 2=drive B, etc.) and a pointer to a 
64-byte buffer. The complete pathname to the current directory will be 
placed in this buffer. The pathname will be terminated by a zero byte. If the 
function is called when the main directory is active, no pathname will be 
returned. In this case, the first byte in the buffer will contain zero. After the 
call, DO must contain the value zero. If the value is negative, an error 
occurred, for example if an incorrect drive number was passed. 


move.w #0,-(sp) Get pathname of the current drive 
pea buffer Address of the 64-byte buffer 
move.w #$47,-(sp) Function number 

trap #1 


addq.1 #8,sp 


buffer: 
me 128 Better to play it safe 


$48 MALLOC 


C: long Malloc (number) 
long number; 


The MALLOC function and the two that follow it, MFREE and 
SETBLOCK, are concerned with the memory organization of GEMDOS. 
As already mentioned in conjunction with function $31, KEEP PROCESS, 
a program is assigned all of the entire memory space available after it 1S 
loaded. This is uncritical in many cases, because only a single program 1s 
running. 
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There are applications under GEM in which at least a part of memory 1s free 
from the start of the program, to allow memory to be called for different 
GEM functions with MALLOC. One good example is the item selector box, 
which will not appear when no more memory 1s available. 


Other applications are programs which work with overlays, for example. To 
load an overlay from the diskette, GEMDOS must have memory available. 
For this reason, every program must only have enough memory reserved 
for program and data code. The unused memory can then be returned to 
GEMDOS by the SETBLOCK command. 


If the program needs some of the memory it released, it can request memory 
from GEMDOS via the function MALLOC (memory allocate). The number 
of bytes required is passed to MALLOC. After the call, DO contains the 
Starting address of the memory area reserved by the call or an error message 
if an attempt is made to reserve more memory than is actually available. 


If -1L is passed as the number of bytes to be allocated, the number of bytes 
available is returned in DO. 


Example 1: 
move.l #-1,-(sp) Determine number of free bytes 
move.w #$48,-(sp) Function number 
Ezap #1 
addq.1l #6,sp Number of free bytes in DO 
Example 2: 
move.l #$1000,-(sp) Get hex 1000 bytes for the program 
move.w #548,-(sp) Function number 
trap # 1 
addq.1l #6,sp 
Te kns Vie Error or address of memory? 
bmi error Negative long word = error! 
move.l d0,mstart Else start addr of the reserved area 
MeUa Li: 
Ms hn ede 9 es 
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$49 MFREE 


C: long Mfree (addr) 
bong. adar; 


An area of memory reserved with MALLOC can be released at any time 
with MFREE. To do this, GEMDOS is passed the address of the memory 
to be released. The value will usually be the address returned by MALLOC. 


If a value of zero is returned in DO, the memory was released by GEMDOS 
without error. Negative values indicates errors. 


move.l mstart,-(sp) Addr of a previously allocated area 
move.w #$49,-(sp) Function number 
trap #1 
addq.1 #6,sp Number of free bytes in DO 
Ee Gigs | 0 Error? 
bne error DO<>0 is error! 
MmBCart.: 
POS ea): 


$4A SETBLOCK 


C: int Mshrink(dummy, block, newsize) 
word dummy = 0; 
LONG. DLOCK? 
long newsize; 


In contrast to the MALLOC function, a specific area of memory can be 
reserved with the function SETBLOCK. The memory beginning at the 
specified address is returned to GEMDOS, even if it was reserved before. 
This function can be used to reserve the actual memory requirements of a 
program and release the remaining memory. 


The parameters the function requires are the starting address and the length 
of the area to be reserved. The area specified with these parameters is then 
reserved by GEMDOS and is not released again until the end of the program 
or after calling the MFREE function. 
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Usually programs will begin with the following command sequence or 
something similar. After the call, DO must contain zero, otherwise an error 


Occurs. 
move.l a7,a5 Save stack pointer in Ad 
move.l #ustck,a7 Set up stack for the program 
move.l 4(a5),a5 A5 now points to the base-page start 
exactly $100 bytes below the prg start 
move.l $c(a5),d0 $C(A5) contains length of the prg area 
add.1l $14(a5),d0 $14(A5) containing the length of the 
initialized data area 
Scat: SiC lao) a0 $1C(A5) contains length of the 
uninitialized data area 
add.1l #$100,d0 Reserve $100 bytes base page 
move... -O0,—(sp) DO contains the length of the area 
to be reserved 
move.l a5,-(sp) A5 contains the start of the area 
to be reserved 
move.w #0,-(Ssp) Meaningless word, but still necessary! 
move.w #$4a,-(sp) Function number 
trap #1 
add.1l #12,sp Clean up the stack as usual 
Pet ws “a0 Dad an error occur? 
bne error Stop 
Here the program continues... 
$4B EXEC 
C; tong Pexeo (mode,- ptrl, perzZ; DET) 
int mode; 
chat *peEris 
Snare or rs 
Chat “OES? 


The Pexec() function permits loading and chaining programs. If desired, the 
program loaded can be automatically started. In addition to the function 
number, the addresses of three strings and a mode word are expected on the 


Stack. 


Let's talk a bit about the mode word. This word has a value of 0, 34 :or5; 
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Mode=0 represents the LOAD'N'GO option: In this case, the file is loaded 
from diskette and the filename and pathname are received in PTR1. PTR2 
contains the option of the command tail, comparable to choosing .TTP in a 
dialog box. PT'R2 stands for the environment string, which apparently has 
no function under GEMDOS. If the command tail and the environment 
string aren't used, then there is a null-byte at this point. 


After loading the program, the system automatically starts the program. The 
called program, started by the Pexec() call, remains in memory. Eventually 
opened files will pass on the most recently started program. This new 
program will be classified as a ‘child process."' Once the child process is 
done, control returns to the original program, or "parent process." 


If the mode word 1s a three, the parameters PTR1 to PTR3 are handled in 
the same form as when mode = O, except that the program will not be 
executed once it is loaded into memory. After calling Pexec() with mode = 
3, the address of the basepage of the loaded program is found in DO. 


At first glance this may not make sense, but this function is the minimum 
that any good debugger should have. When you want to search a program 
for errors with a debugger, you would want control to go to the debugger, 
instead of the program loading and immediately executing. If the program 
ran without the debugger, and it had errors, it would crash. The LOAD 
option of Pexec() offers help. 


If the mode word = 4, the program found in memory will be started. PTR1 
waits for the address of the necessary basepage. PTR2 and PTR3 are 
unused. This way you can start a program previously loaded with Pexec(), 
mode —_3. 


The last option is a mode word of 5. This option sets up the basepage in 
memory, as well as allocating the largest free block of memory. Naturally, 
no more data can go into the basepage after this call, especially text, data 
and BSS ranges. These must be provided for by the programmer. 


pea env Environment 

pea com Command line 

pea fia) Filename 

move.w #0,-—(sp) Load and start, please 

move.w #5S4b,-(sp) Function number 

trap #1 

add.l #16,sp Here we come to the end of the 


chained program or loaded module 
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P21 Load sort routine 
sie b. soSsOre. pro. 

com: Sort the file in ascending order 
Je oid UO slat apa G sgod 

env: No environment 
OCs. o 

$4C TERM 


C: void Pterm(retcode) 
int retcode; 


TERM $4C represents the third method, after Pterm0(), function number 
$00, and Ptermres(), function number $31, of ending a program. Pterm() 
automatically makes the memory used by the program available to 
GEMDOS again. Unlike TERM $00, however, a programmer-defined value 
other than zero can be returned to the caller. This allows a short message to 
be passed back to the calling program. 


All files opened in this process will be automatically closed from PTERM. 


move.w #37,-(sp) Any 2-byte value 
move.w #$4c,-(sp) End program 
trap #1 OW 


We never get here 


$ 4E SFIRST 


C: int Fsfirst(fnam,attr) 
char *fnam; 
int’ ‘attr: 


The SFIRST function can be used to check to see if a file with the given 
name is present in the directory. If a file with the same name is found, the 
filename, the file attribute, data and time of creation, and the size of the file 
in bytes 1s returned. This information is placed in the DTA buffer, whose 
address is set with the SETDTA function, by GEMDOS. 
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One feature of this function is that the filename need not be specified in its 
entirety. Individual characters in the filename can be exchanged for a 
question mark "?", and entire groups of letters can also be replaced by a 
"*«"" In the extreme form a filename would be reduced to the string "*.*". In 
this case the first file in the directory would satisfy the conditions and the 
filename would appear in the DTA buffer along with the other information. 


In addition to the filename, the SFIRST function must also be given a 
search attribute. The possible parameters of the search attribute correspond 
to the attributes which can be specified in CHMOD function: 


$00 = Normal access, read/write possible 

$01 = Normal access, write protected 

$02 = Hidden entry (ignored by the ST desktop) 
$04 = Hidden system file (ignored like $02) 
$08 = Volume label, diskette name 

$10 = Subdirectory 

$20 = File will be written and closed 


The following rules apply when searching for files: 


° If the attribute word 1s zero, only normal files are recognized. 
System files or subdirectories are not recognized. 
° System files, hidden files, and subdirectories are found when 


the corresponding attribute bits are set. Volume labels are not 
recognized, however. 


° In order to get the volume label, this option must be expressly 
set in the attribute word. All other files are then ignored. 
» After the call, DO contains zero if the desired file has been 


found. The 44-byte DTA buffer is then constructed as follows: 


Bytes 0-20 Reserved for GEMDOS 

Byte ou File attribute 

Bytes 22-23 Clock time of file creation 
Bytes 24-25 Date of file creation 

Bytes 26729 File size in bytes (long) 
Bytes 30-43 Name and extension of the file 


If, however, no file is found which corresponds to the specified search 
String, the error message -33, file not found, is returned. 


pea dta Set up DTA buffer 
move.w #la,-—(sp) Function number SETDTA 
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trap #1 
addq.1l #6,SP 
move.w #attrib,-(sp) Attribute value 
move.l #filnam,-(sp) Name of file to search for 
move.w #$4e,- (sp) Function number 
trap #1 
addq.1 #8,sp 
cet do File found? 
bne notfound Apparently not 
SaCETID: 
Ee 3 od & Same 9, Search for normal files only 
filnam: 


.dce.b "*.*",0 Search for the. 1st possible file 


dta: 
.ds.b 44 Space for the DTA buffer 


$4F SNEXT 


Cr int oP srexst 1) 


The SNEXT function (Search next) can be used to see if there are other files © 
on the disk which match the filename given. To do this, only the functior 
number need be passed; SNEXT does not require any parameters. All of the 
parameters are set from the SFIRST call. 


If the search string is very global, as in the previous example, all of the files 
on a diskette can be determined and displayed one after the other with 
SFIRST and SNEXT. This makes it rather easy to display a directory 
within a program. The SNEXT function is called repeatedly and the 
contents of DO are check afterwards. If DO contains a value other than zero, 
either an error occurred, or all of the directory entries have been searched. 


move.w #S4f,-(sp) Search next 

trap #1 is te Sbath there? 

addq.1 #2,sp 

ESE wl 6 No more by negative values 
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$56 RENAME 


C: int Frename(dummy, oldname, newname) 
int dummy = 0; 
char*oldname; 
char *newname; 


Files are renamed under GEMDOS with the RENAME function, which 
requires two pointers to file or pathnames. The first pointer points to the 
new name, with the specification of the pathname if necessary; the second 
pointer points to the previous name. A 2-byte parameter is required in 
addition to the two pointers. We were unable to determine the function of 
the additional word parameter. Different values had no (recognizable) effect. 


As a return value, DO contains either zero, meaning that the name was 
changed correctly, or an error code. 


pea newnam New filename 

pea oldname File to rename 

move.w #0,-(sp) Dummy 

move.w #$56,-(sp) Function number 

trap #1 

add.1l #12,sp 

ES. a0 Test for error 

oldnam: Don't forget zero byte at end! 
OOo" "6S. bevaae oO 

newnam: 


.dc.b '‘'newname.dat',0O 


$57 GSDTOF 


C: void Fdatime(timeptr, handle, flag) 
int. handle; 
char *timeptr; 
5G. Llag: 


If the directory is displayed as text rather than icons on the desktop, the date 
and time of file creation as well as the size of the file in bytes is shown. The 
time and date can either be set or read with function $57. To do this it is 
necessary that the file be already opened by OPEN or CREATE. The handle 
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number obtained at the opening must be passed to the function. Additional 
parameters are a word which acts as a flag as to whether the time and date 
are to be set (0) or read (1), and a pointer to a 4-byte buffer which either 
contains the result or will be provided with the required data before the call. 


This date buffer contains the time in the first two byes and the date in the 
last two bytes. The data format is identical to that of the functions for 
setting/reading the time and date. 


A word of warning about this section. Programmers who call this function 
in C and assembler must make allowances. In the include file OSBIND.H, 
the parameters 'timeprt' and ‘handle’ are exchanged. A C call must follow 
this scheme when using the abovementioned include file. In assembler 
programs, however, the normal sequence of parameters must be followed. 


Example 1: 


move.w #1,-(sp) Read time and date 
pea Source 4 byte buffer 
move.w #handle,-(sp) File must first be opened 
move.w #$57,-(sp) Function number 
trap #1 
add.1 #10,sp 
handle: 
HS 2 
punt: 
(GS. © <4 


Example 2: 


move.w #0,-(sp) Set time and date 
pea buff 4 byte buffer 
move.w #handle,-(sp) File must first be opened 
move.w #$57,-(sp) Function number 
trap #1 
add.l +#10,sp 
handle: 
IS Se 
Mutts 
SAS Sry UE 
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3.1.1 Memory, files and processes 


Will it never end? You just mastered getting around the operating system of 
your C-64, Atari 800 or other 8-bit machine, then suddenly you're 
confronted with new things such as memory management, handles, and 
even parent/child processes. Other computers don't have these knickknacks. 
Is it really that important to have them? Doesn't the computer run fine 
without them? And then there are these types that don't stay at the memory 
address you want them to operate. It was so much simpler in the past. 
Those were the days when you knew where a program loaded and ran, and 
when you assembled things at the necessary addresses. 


I/O conversion, Malloc, basepage, Pexec or Dup are such obscure terms. 
Yes, everything was a lot simpler in the good old days. 


We're here to help you overcome the "culture shock" that hits most 8-bit 
owners when they get a 16-bit computer. In order to ease you into the most 
effective use of the Atar1 ST operating system, we want to show you what 
special functions like MALLOC, SETBLOCK, TERM and PEXEC are, as 
well as the use and design of the basepage. We'll close with DUP and 
FORCE, the input/output division. 


The concept of memory processing 


When the ST is first turned on, it goes through a normal boot sequence. 
This sequence happens regardless of the ROMs or operating system in your 
ST. The system boots, then displays the Desktop on the monitor. 


Up to this time there have already been a number of procedures done within 
the ST. So other memory, peripheral chips and operating system routines 
are initialized, and the programs in the Auto folder executed. 


The Desktop itself 1s an independent program, the same as an editor, 
BASIC interpreter or compiler. Whether it is in ROM or on the TOS.IMG 
disk, it starts like a program loaded from disk. One specific task of the 
Desktop is to load other programs and give computer control to these 
programs. As we said earlier, we'll take a closer look. 


The function call Pexec is used by the Desktop in loading programs. When 


you choose a program with the mouse, a corresponding Pexec call with the 
filename and parameters given in the dialog box is executed. GEMDOS 


145 


Abacus Software Atari ST Internals 


takes control from the call and looks for free memory. But what's "free 
memory"? Every program has its memory range; free memory is 
unoccupied memory, into which a program can be loaded. The start of free 
memory (TPA) will then have a basepage added to it. This basepage is 256 
bytes ($100 bytes) in size, and contains special information about the 
program being loaded. The basepage’s design looks like this: 


0x00 p_lowtpa Pointer to start of basepage 

Ox04 p_ hitpa Pointer to the end of free memory 
Ox08 p _tbase Pointer to beginning of program (text segment) 
OxOc p_tlen Program size (Text segment) 

Ox10 p_dbase Pointer to start of data segment 
Ox14 p-oLen Data segment size 

Ox18 p_bbase Pointer to beginning of BSS segments 
Oxlc p_len BSS segment size 

0x20 p dta Pointer to DTA buffer 

Ox24 p_parent Pointer to parent's basepage 

Ox28 (reserved) 

OE p_env Pointer to environment string 

Ox80 cmdlin Command line 


The range between 0x30 and Ox7f is used by the operating system. You 
should not use this range. 


Although the basepage is sent from the system, there aren't many other 
things that need to be done. First, after the program is loaded directly 
behind the basepage, the data 1s made available and put into the appropriate 
areas. 


The program is relocated after loading (if needed). The programmer as a 
rule ias no control over the memory where the program resides, since 
Pexec controls the free memory, and loads the program into that memory. 
The classic 8-bit computer must load a program into a specific range of 
mem ory, which easily allows combining multiple programs into one 
memury register. These combinations should be avoided at all costs under 
“proper GEMDOS programming. Instead, assemble the program, putting 
relevant addresses into a loader that Pexec will load first, then act upon 
these addresses before loading the main program. 


The program will start after this work. It is now a child of a program that it 
has called. The calling program will be identified as a parent. This parent 
has no gender; the general reference of parent and child solves any linguistic 
problems. 
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For the moment, let's concentrate on the child. This process has from the 
first set up the entire free memory needed. The first action should be to 
determine the amount of memory needed in any program, and hand the rest 
over to GEMDOS. And how do you allocate memory? Once you know it, 
it's simple to follow. 


After the start of the program, you'll find the address of the basepage on the 
stack. All the program data and calculations for memory requirements is in 
the basepage. These data are p tlen, p dlen and p_ blen. Add these values 
together, and there you have your range needed by the program. In 
addition, you have to reserve memory for the stack, which lies in protected 
memory. 


When you analyze the beginning of a program with a disassembler, you'll 
frequently find the following or a similar sequence: 


move.l a/,a5 store stack to determine basepage 

move.l 4(a5),a5 base page is now in a5 

move.l $c(a5),d0 text segment length stands in dO 

add.l $14(a5),d0O add to that the length of the data- and 

add.l S$lc(a5),d0O the bss segments 

add.l1 #5500,d0 and to that add the amount needed for the stack 


move ..l. -d0,.al 


agG..- “al ,ai length + address of basepage 

and.1 #<2,d1 be sure that the stack starts at an even address 
move.l1 dl,a/7 now put the stack where you want it 

move.l1 d0,-(sp) size of reserved area 

move.l a5,-(sp) from where you want it reserved (base page) 

Cl rom. i (Sp) dummy 

move.w #$4a,-(sp) setblock-function number 

trap #1 call gemdos 

add.l #12,sp and clear off the stack 


This program section takes up all tasks which were demanded from 
GEMDOS. After GEMDOS has reduced the amount of available memory 
accordingly, the program can then continue. 


What is released memory? This is done by GEMDOS for further Pexec 
calls. The child process has no access authority. You should ideally be able 
to use memory without further measurements. When you keep putting data 
into this range, the data could occasionally become "overstuffed". Different 
functions of GEMDOS, the VDI and AES are reserved by Malloc, and 
putting data into the received range. When you haven't protected your data, 
the chances are good that you'll lose your data. 
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When you have not set up available memory, then you can call Malloc from 
the operating system. After the call, you get the starting address of the 
reserved range. This range is "safe'"—you can't put any other process into 
this range. When the memory is no longer free, the best thing to do is call 
Mfree. Then you can choose from another process. 


When you hold to these conventions, then one can't get past. The memory 
is again protected, and you can load in any other programs. Every new 
loading makes up another child of the parent program. So overlaying 
programs is only allowed when the available memory 1s protected. 


If a program ends with PtermO or Pterm, then the designated memory is 


released from the program. Additional memory reserved by Malloc will be © 


released. Also, any open files will be closed. Then control returns to the 
parent, whereas it was previously held by the child. 


Handles, files, devices 


The basic file handling functions in GEMDOS are quite simple. Fopen or 
Fcreate open a file; this file 1s read from with Fread, and written to with 
Fwrite. Fclose closes the file. All file accesses run under a number, initially 
stated 1n Fopen or Fcreate. This number between 6 and 45 is called a "non 
standard handle.'"' Non standard handles are used only in conjunction with 
files. 


It is logical to assume that there are also "standard handles." And so there — 


are; these are the handles between 0 and 5. These handles can be organized 
as either a file or as a ‘character device." Character devices in the ST consist 
of the keyboard, the monitor, the printer interface and the serial interface. 
Here is the normal assignment for these standard handles: 


Handle Device 
0 Console input (Stdin) 
ti Console output (Stout) 
Ps Serial interface (AUX) 
3 Printer interface (PRN) 


The standard handles 4 and 5 aren't used in ST GEMDOS as a rule. The 
“correct’’ GEMDOS layout sees handle 2 as a standard error device (Stderr). 
These will shift AUX and PRN over one place. Handle 5 is originally used 
as a null-device. This null-device can store output in an empty space. This 
setup is unfortunately not implemented in the ST. 
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That's not all. There are also character handles which are assigned in 
connection with the character devices. These character handles are received 
only after an Fopen or Fcreate, and give the names of the desired character 
devices. The names of the character devices are "CON:", "AUX:" and 
“PRN:". 


Standard handles serve two distinct purposes. The first is that you can use 
them for Fopen or Fcreate without actually having Fopen or Fcreate. These 
handles will perform any process arranged by the parent process. The 
second purpose is the allowance for altering standard handles. 


For example: You work on a program which waits for a quantity of data 
from the keyboard; this data is processed, saved to disk, and the results sent 
to a printer. Now, you could do every test run by hand, and end up with a 
pile of paper, until the program runs free of error. However, you could just 
as easily pass along the keyboard input and the printer output by writing all 
the keyboard input into a file, and having the file data do the typing. You 
could also have the printer output sent to a file instead of the printer, so you 
could save yourself a waste of paper, and still see the result later. 


These conversions use both standard and non standard handles, controlled 
by the Force function. Here is a program fragment which contains the 
necessary calls for using a file to send "keyboard" input from a file: 


move.w #0,-(sp) "read only" mode 

pea fil nam name of the input file 
move.w #$3d,-(sp) fopen() 

trap #1 gemdos call 

addq.1l #8,sp 

tse. a0 did fopen work? 

bmi Opn. Ere negative long is an error! 
move.w d0,f handle the handle we need is our 
move.w d0,-(sp) our non std handle 

move.w #0,-(sp) std handle console 

move.w #S$46,-(sp) force() 

trap #1 call gemdos 

addq.1 #6,sp 

Pete «a0 read error 

bmi EFC err 


input starts from 
file here 


After this call (and this is extremely important), every GEMDOS call for a 
character from the keyboard will get it from the file. The keyboard must not 
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be read with Fread(). Cconin(), Crawio(), Cconrs() and the other functions 
dealing with keyboard data also look to the file data instead of the keyboard. 
The use of character functions (Conin, etc.) in connection with this are 
problematical. These functions have no options in working with the called 
program when the file ends. This information can be had only by using the 
FreadQ) function. 


An exception is when you mark the input file with a special end-of-file 
(EOF) indicator. One character frequently used for this purpose is 
<Control><Z>, with an ASCII value of 26 or Oxla. When you reserve this 
character for an EOF character, then you can read this character in addition 
to the standard arrangement of 0. For particularly elegant programming, you 
can follow it with the Fdup function. Here's a short example: 


move.w #0,-(sp) our std handle 

move.w #5$45,-(sp) dup () 

trap #1 call gemdos 

addgq.l #4,sp 

tstizd do was there still a non std handle free? 

bmi no more evidently not 

move.w d0,dup han make a note of it! 
* here the key/file transfer program can follow 
* Here is the program itself. Now you can only start with keyboard 
* input 


move.w dup _han,-(sp) our non std handle from dup() 


move.w #0,-(sp) there should be a std handle 
move.w #5$46,-(sp) force () 

trap #1 call gemdos 

addq.1 #6,sp 

Cst .L do read error 

bmi fre err 


from this point on, the input is: again 
handed over to the keyboard 


First, the handle from Stdin, the O, is duplicated by the Dup function. The 
keyboard is accessed by the standard handle as well as the non standard 
handle. (only with Fread, naturally). The input routine then switches over to 
the file, giving the effect described above. All characters that you would 
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normally send over the keyboard are read from the file. When the input is 
ended, then the duplicated handle is returned to keyboard input with a Force 
call. The still open file should be closed by an Fclose call. 


From reading the above, it should be clear to you the way that the printer 
output works. Again, open a file with Fcreate(). The handle used can be 
Forced from the printer. Then all data that would normally go to the printer 
will be sent to a file. 


A further application would be when you move output from the screen to 
the printer. This can also be easily realized. 


GEMDOS error codes and their meaning 


The GEMDOS functions return a value giving information about whether or 
not an error occurred during the execution of the function. A value of zero 
means no error; negative values have the following meanings: 


ate Invalid function number 

meh: File not found 

-34 Pathname not found 

=) Too many files open (no more handles left) 
36 Access not possible 

—37] Invalid handle number 

=o Not enough memory 

-40 Invalid memory block . address 

—46 Invalid drive specification 

-49 No more files 


In addition to these error messages, the BIOS error messages may occur. 
These error messages have numbers -1 to -31 and are described in section 
ee, 
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3.2 The BIOS Functions 


The software interface between GEMDOS and the hardware of the computer 
is the BIOS (Basic Input Output System). The BIOS, as the name suggests, 
is concerned with the fundamental input/output functions. This includes 
screen output, keyboard input, printer output, RS-232 functions and, of 
course, disk input and output. 


The BIOS functions are also available to user programs. The TRAP 
instruction of the 68000 processor is used to call them. Any data required is 
passed through the stack and the result of the function 1s returned in the D?— 
register. The machine language programmer should be aware that the 
contents of DO-D2 and AO-A2 are changed when calling BIOS functions; 
the remaining registers remain unchanged. 


BIOS function calls are even simpler if you program in C. Here you can use 
simple function calls with the corresponding parameter lists. The function 
calls are stored as macros in an include file. In the examples, the definition 
of the function and its parameters in C will be shown. For assembly 
language programmers, the use is described in an example. 


TRAP #13 1s reserved for the BIOS functions. 
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0 Getmpb get memory parameter block 


C: void Getmpb (pointer) 
long pointer; 


Assembler: 


move.l pointer,-(SP) 
move.w #0,-(SP) 

trap #13 

addq.l1 #6,sp 


This function fills a 12-byte block whose address is contained in pointer 
with the memory parameter block. This block contains three pointers: 


long mdmfl Memory free list 
long mdmal Memory allocated list 
long md rover Roving pointer 


The structures to which each pointer points are constructed as follows: 


LONG =:) mid: JUL nik Pointer to next. block 
LOG oy (Mc. St art Start address of <tne DlLOcKk 
long md length Lengten- of the block 1n bytes 
long md_own Process descriptor 

Example: 


move.l #buffer,+(sp) Buffer for MPB 


move.w #0,-(sp) getmpb 
ae ays &. #13 Caicd:. -BLOS 
addq.l #6,sp Stack correction 


We get the values $48E, 0, and $48E. The following data are at address 
$48E (for IMB RAM): 


m link 0 No additional block 

M.Stare -S35900 Start address of the free memory 
m length $3C700 Length of the free memory 

m own 0 No process descriptor 
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1 Beconstat return input device status 


C: int Bconstat (dev) 
int dev; 


Assembler: 


move.w dev,-(sp) 
move.w #1,-(sp) 
trap #13 
addq.1l #4,sp 


This function returns the status of an input device, defined as follows: 


Status 0 No characters ready 
Status —2 (at least) one character ready 


The parameter dev specifies the input device: 


dev Input device 
0 PRT:, Centronics interface 
i. AUX:, RS-232 interface 
Z CON:, Keyboard and screen 
3 MIDI, MIDI interface 
4A IKBD, Keyboard port 


The following table lists the allowed accesses to these devices: 


Operation PAL: AUX: CON: MIDI IKBD 
lnpuc Sstalus no yes yes yes no 
Input yes yes yes yes no 
OULPUC. SLaLus:, (yes yes yes yes yes 
Output yes yes yes yes yes 


This example waits until a character from the RS-232 interface is ready. 


wait move.w #1,-(sp) RS-232 
move.w #1,-(sp) bconstat 
trap #13 
addq.l #4,sp 
cSt do character available? 
beq wait no, wait 


SN i a a 
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2 Bconin read character from device 


C: long Bconin (dev) 
int dev; 


Assembler: 


move.w dev,-(sp) 
move.w #2,-(sp) 
trap #13 
addq.1 #4,sp 


This function fetches a character from an input device. The parameter dev 
has the same meaning as in the previous function. The function returns 
when a character is ready. 


The character received 1s in the lowest byte of the result. If the input device 
was the keyboard (con, 2), the key scan code is also returned in the lower 
byte of the upper word (see the description of the keyboard processor). 


Example: 
move.w #2,-(sp) con 
move.w #2,-(sp) bconin 
trap #13 


addq.l #4,sp 


3 Beonout write character to device 


C: “void -Beonout (dev,;“c} 
int--dey, Cc? 


Assembler: 


move.w c,- (sp) 


move.w dev,-(sp) 
move.w #3,-(sp) 
trap #13 


addq.1l #6,sp 
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This function serves to output a character ''c" to the output device dev 
(meaning is the same as for the previous function). The function returns 
when the character has been outputted. 

Example: 


move.w #'A',-(sp) 


move.w #0,-—(sp) PRIS 
move.w #3,-—-(sp) BOonouct 
trap #13 


addq.1 #6,sp 


The example outputs the letter ''A" to the printer. 


4 Rwabs read and write disk sector 


C: long Rwabs(rwflag, buffer, number, recno,dev) 
£ong:- puller; 
Inc. rwitag, nowber, recno, dev: 


Assembler: 


move.w dev,-(sp) 
move.w recno,-(sp) 
move.w number,-(sp) 
move.l buffer,-(sp) 
move.w rwflag,-(sp) 
move.w #4,-(sp) 
trap #13 


add.l #14,sp 


This function serves to read and write sectors on the disk. The parameters 
have the following meanings: 


rwflag Meaning 


0 Read sector 

di Write sector 

2 Read sector, ignore disk change 
3 Write sector, ignore disk chance 
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The parameter buffer 1s the address of a buffer into which the data will be 
read from the disk or from which the data will be written to the disk. The 
buffer should begin at an even address, or the transfer will run very slowly. 


The parameter number specifies how many sectors should be read or written 
during the call. The parameter recno specifies which logical sector the 
process will start with. 


The parameter dev determines which disk drive will be used: 


dev Drive 
0 Drive A 
fi Drive B 
2+ Hard disk, RAM disk, network 


The function returns an error code as the result. If this value is zero, the 
operation was performed without error. The returned value will be negative 
if an error occurred (please see the Floprd entry of the XBIOS listing for 
error codes and their meanings). 


Example: 
move.w #0,-(sp) Drive A 
move.w #10,-—(sp) Start at logical sector 10 
move.w #2,-(sp) Read 2 sectors 
move.l #buffer,-(sp) Buffer address 
move.w #0,-—-(sp) Read sectors 
move.w #4,-(sp) rwabs 
trap #13 


add.l #14,sp 


buffer asp 2 sorZ 
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5 Setexec set exception vectors 


C: long Setexec (number, vector) 
int number; 
LONG. VeC Lon; 


Assembler: 


move.l vector,-(sp) 
move.w number,-(sp) 
move.w #5,-(sp) 
trap #13 

addq.1l #8,sp 


The function setexec allows one of the exception vectors of the 68000 
processor to be changed. The number of the vector must be passed in 
number and the address of the routine pertaining to it in vector. The 
function returns the old vector as the result. If you just want to read the 
vector, pass the value -1 as the new address. The 256 processor vectors as 
well as 8 vectors for GEM, which numbers $100 to $107 (address $400 to 
$41C) can be changed with this function. 


Example: 
move.l #buserror,-(sp) 
move.w #2,-(sp) 
move.w #5,-(sp) 
trap #13 
addq.1l #8,sp 


buserror 
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6 Tickcal return millisecond per tick 


C: long Tickcalt(?) 


Assembler: 


move.w #6,-—(sp) 
trap #13 
addq.1l #2,sp 


This function returns the number of milliseconds between two system timer 
calls. 


Example: 


move.w #6,-(sp) 
Erayp #13 
addq.1l #2,sp 


Result: 20 ms 


7 Getbpb get BIOS parameter block 


C: long Getbpb (dev) 
int dev; 


Assembler: 


move.w dev,-(sp) 
move.w #/7,-(sp) 
Lia #13 
addq.1 #4,sp 


This function returns a pointer to the BIOS Parameter Block of the drive 
dev (O=drive A, 1=drive B). 


The BPB (BIOS Parameter Block ) is constructed as follows: 


int recsiz Sector size in bytes 
Pn “CisizZ Cluster size in sectors 
Lie. OLS 126 Cluster size in bytes 
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int rdlen 
Int. Siz 
int fatrec 
int datrec 
Int —. nine L 
Int: bElags 


Directory length in sectors 


FAT size in sectors 


Atari ST Internals 


Sector number of the second FAT 
Sector number of the first data cluster 
Number of data clusters on the disk 


Misc. flags 


The function returns the address $3E3E for drive A and the address $3E5E 


for drive B. An address of zero indicates an error. 


Example: 


move.w #0,-(sp) 
move.w #7,-—-(sp) 


Crap #13 
addq.1 #4,sp 


Drive A 
getbpb 


Here are the BPB data for 80 track single and double-sided disk drives: 


Parameter 
recsiz 
clsiz 
Gisi2h 
rdlen 

1 es 
fatrec 
datrec 
ghbhey ede 


80 track SS 


80 track DS 


3 A 
2 2 
1024 1024 
f 7 

> = 

6 6 

18 18 
Soe yea 


rence SS sss ls SSNS 
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8 Bcostat return output device status 


C: long Bcostat (dev) 
mnt. dev; 


Assembler: 


move .w dev,-(sp) 
move.w #8,-(Ssp) 
trap #13 
addq.l #4,sp 


This function tests to see if the output device specified by dev 1s ready to 
output the next character. dev can accept the values which are described in 
function one. The result of this function is either -1 if the output device is 
ready, or zero if it must wait. 


Example: 
move.w #0,-(sp) Printer ready? 
move.w #8,-(sp) beostat 
trap #13 


addq.1l #4,sp 


9 Mediach inquire media change 


C: long Mediach (dev) 
int dev; 


Assembler: 


move.w dev,-(sp) 
move.w #9,-(sp) 
trap #13 
addq.l #4,sp 


This function determines if the disk has been changed. The parameter dev, 
the drive number (O=drive A, 1=drive B), must be passed to the routine. 
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One of three values can occur as the result: 


0 Diskette was definitely not changed 

iy Diskette may have been changed 

Z Diskette was definitely changed 
Example: 

move.w #1,-(sp) Drive B 

move.w #9,-(sp) mediach 

trap #13 


addq.l1 #4,sp 


10 Drvmap inquire drive status 


C: long Drvmap () 


Assembler: 


move.w #10,-(sp) 
trap #13 
addq.l1 #2,sp 


This function returns a bit vector which contains the connected drives. The 
bit number n is set if drive n 1s available (0 means A, etc.). Even if only one — 
drive is connected, %11 is still returned, since two logical drives are 
assumed. 


Example: 
move.w #10,-(sp) drvmap 
trap #13 


addq.l #2,sp 
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11 Kbshift inquirelchange keyboard status 


C: long Kbshift (mode) 
int mode; 


Assembler: 


move .W 
mode .w 
trap 

addq.1l 


mode, -— (sp) 
“be See (sp) 
#13 

#4,sSp 


With this function you can change or determine the status of the special keys 
on the keyboard. If mode is -1, you get the status, a positive value will be 
accepted as the status. The status 1s a bit vector constructed as follows: 


to 
foe 
ct 


NYDN OP WN FE OC 


Example: 


move .w 
move .w 
Crap 

addq.1l 


Meaning 

Right shift key 

Left shift key 

Control. key 

ALT key 

Caps Lock on 

Right mouse button (CLR/HOME) 
Left mouse button (INSERT) 


Unused 

#-1,-(sp) Read shift status 
#11,—-(sp) kbshite 

#13 

#4,Sp 
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3.3 The XBIOS 


To support the special hardware features of the Atari ST, there are extended 
BIOS (XBIOS) functions, which are called by a TRAP #14 instruction. 
These functions, like the normal BIOS functions, can be called from 
assembly language as well as from C. When calling from C, a small TRAP 
handler in machine language is again necessary, which is contained in 
OSBIND and can look like this: 


trapl4: 
move.l (sp)+,retsave Save return address 
trap #14 Cali -XBIOSs 
move.l retsave,-(sp) Restore return address 
ba 
.bss 
retsave.-.as.£-1 Space for the return address 


Macro functions can be used in C which allow the extended BIOS functions 
(eXtended BIOS, XBIOS) to be called by name. The appropriate function 
number and TRAP call will be created when the macro is expanded. 


When working in assembly language, the function number of the XBIOS 


routine need simply be passed on the stack. The XBIOS has 40 different 
functions whose significance and use are described on the following pages. 
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0 Initmous initialize mouse 


C: void Initmous(type, parameter, vector) 
anc Lype? 
long parameter, vector; 


Assembler: 
move.l vector,-(sp) 
move.l parameter,-(sp) 
move.w type,-—(sp) 
move.w #0, (-sp) 
trap #14 


add.1l #12,sp 


This XBIOS function initializes the routines for mouse processing. The 
parameter vector 1s the address of a routine which will be executed 
following a mouse-report from the keyboard processor. The parameter type 
selects from among the following alternatives: 


Cype 
0 Disable mouse 
ua Enable mouse, relative mode 
2 Enable mouse, absolute mode 
3 unused 
4 Enable mouse, keyboard mode 


This allows you to select if mouse movements are to be reported and in 
what manner this will occur. 


The parameter parameter points to a parameter block, which is constructed 
as follows: 


char topmode 
char: buttons 
char xparam 
char yparam 


The parameter t opmode determines the layout of the coordinate system. A 0 


means that Y=0 lies in the lower corner, 1 means that Y=0 lies in the upper 
corner. 
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The parameter buttons 1S a parameter for the command "set mouse 
buttons" of the keyboard processor (see description of the IKBD, intelligent 
keyboard). 


The parameters xparam and yparam are scaling factors for the mouse 
movement. If you have selected 2 as the type, the absolute mode, the 
parameter block determines four more parameters: 


int xmax 
int ymax 
ne) ae eo Ver mek es 
Int “yetare 


These are the X- and Y-coordinates of the maximum value which the mouse 
position can assume, as well as the start value to which the mouse will be 
set. 


Example: 
move.l #vector,-(sp) Address of the mouse position 
move.l #parameter,-(sp) Address of the parameter block 
move.w #1,-(sp) Enable relative mouse mode 
move.w #0,-(sp) Init mouse 
trap #14 


and... “ie gSp 
Parameter Cer 2 soe 


vector oe Mouse interrupt routine 
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1 Ssbrk save memory space 


C: Long Ssbrk (number) 
int number; 


Assembler: 


move.w number, -(sp) 
move.w #1,-—(sp) 
iLrap #14 

addq.1l #4,sp 


This function reserves memory space. The number of bytes must be passed 
in number. Space is prepared at the upper end of memory. The function 
returns the address of the reserved memory area as the result. This function 
must be called before initializing the operating system, meaning that it must 
be called from the boot ROM, before the operating system is loaded. 


Example: 
move.w #$400,-(sp) Reserve 1K 
move.w #1,-(sp) ssbrk 
crap #14 


addgq.1l #4,sp 
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2 Physbase return screen RAM base address 


Ce Long Phayvspase) 


Assembler: 
move #2,-—-(Sp) 
trap #14 


addq.1 #2,sp 
This function returns the base of the physical screen RAM. The physical 
screen RAM is the area of memory displayed by the video shifter. The result 
is a long word. 
Example: 


SF8000, base address of the screen for 1 MB RAM 
$78000, base address of the screen for 512 KB RAM 


3 Logbase get logical screen base 


C: long Logbase () 


Assembler: 
move #3,-(sp) 
txvap #14 


addq.1 #2,sp 


The logical screen base is the address which is used for all output functions 
as the screen base. If the physical and logical screen bases are different, one 
screen will be displayed while another picture is being constructed in a 
different area of RAM, which will be displayed later. The result of this 
function call is again a longword. 


Example: 


SF8000, base address of the screen for 1 MB RAM 
$78000, base address of the screen for 512 KB RAM 
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4 Getrez return screen resolution 


Ce 2h “Get rez) 


Assembler: 


move.w #4,-(sp) 
trap #14 
addq.l #2,sp 


This function call returns the screen resolution: 


O := Low resolution, 320%*200 pixels, 16 colors 

1 := Medium resolution, 640*200 pixels, 4 colors 

2 := High resolution, 640*400, pixels, monochrome 
Example 


2, monochrome 


5 Setscreen set screen parameters 


C: void Setscreen(logadr, physadr, res) 
long logadr, physadr; 
int res; 


Assembler: 


move.w res,-(sp) 
move.l physadr,-(sp) 
move. |. -1odqadr,—(sp) 
move.w #5,-(sp) 
trap #14 

add.l #12,sp 


This function changes the screen parameters which can be read with the 
previous three functions. If a parameter should not be set, a negative value 
must be passed. The parameters are set in the next VBL routine so that no 
disturbances appear on the screen. 
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Example: 
move.w #-1,-(sp) Retain resolution 
move.l #$70000,-(sp) Physical base 
move.l #$70000,-(sp) Logical base 
move.w #5,-(sp) setscreen 
trap #14 : 


add.1° “Fi2;5sp 


Sc the physical and the logical screen address to $70000, retain the 
resolution. 


6 Setpalette set color palette 


C: void Setpalette (paletteptr) 
long paletteptr; 


Assembler: 


move.l paletteptr,-(sp) 
move.w #6,-(sp) 

trap #14 

addq.1 #6,;Sp 


A new color palette can be loaded with this function. The parameter 
paletteptr must be a pointer to a table with 16 colors (each a word). The 
address of the table must be even. The colors will be loaded at the start of 
the next VBL. 


Example: 
move.l #palette,-(sp) Address of the new color palette 
move.w #6,-(sp) set palette 
trap #14 


addq.l #6,sp 


palette dc.w $777,3700,$070,$007,$111,$222,$5333,5444 
do..w, §555,3000,$001,.5010,5100, 320075020; S002 
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7 Setcolor set color 


Crane Setcolormeolormum, Cor1cr) 
Int colormmum, -col1or 


Assembler: 


move 
move 
move 
LLap 


addq. 


-W 
WwW 
~wWw 


a 


color,-(sp) 
colornum, - (sp) 
ti 7 (Sp) 

#14 

#6,Sp 


This function allows just one color to be changed. The color number (0-15) 
and the color belonging to it (0-$777) must be specified. If -1 is given as the 
color, the color is not set but the previous color is returned. 


Example: 


move 
move 
move 
trap 


addq. 


-W 
-W 
WwW 


2. 


#$777,-(sp) Color white 
#1,-(sp) As color number 1 
+/,—(sp) 

#14 

#6,Sp 
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8 Floprd read diskette sector 


C: int Floprd(buffer, filler, dev, sector, track, side, 
count) 

long: buttexs,) fi tier: 

int. Mev, Sector, Crack, Side, Counc; 


Assembler: 
move.w count,- (sp) 
move.w side, -(sp) 
move.w track, -(sp) 
move.w sector,-(sp) 
move.w dev,-(sp) 


Cisse, -~1ta) 

move.l buffer,-(sp) 
move.w #8,-(sp) 
trap #14 

add.1l #20,sp 


Tis function reads one or more sectors in from the diskette. The parameters 
have the following meaning: 


count: Specifies how many sectors are to be read. Values between 
one and nine (number of sectors per track) are possible. 


side: Selects the diskette side, zero for single-sided drives and 
zero or one for double-sided drives. 


track: Determines the track number (0-79 for 80-track drives or 
Q-39 for 40-track drives). 


sector: The sector number of the first sector to be read (1-9). 

dev: Determine drive number, 0 for drive A and 1 for drive B. 

filler: Unused long word. 

buffer: Buffer in which the diskette data should be written. The 
buffer must begin on a word boundary and be large enough 


for the data to be read (512 bytes times the number of 
sectors). 
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The function returns an error code which has the following meaning: 


O OK, no error 

-l General error 

-2 Drive not ready 

-3 Unknown command 

mi- SRC. error 

-5 Bad request, invalid command 

-6 Seek error, track not found 

-7 Unknown media (invalid boot sector) 

-8 Sector not found 

=o > (NO pPpapes) 

-10 Write error 

-l1 Read error 

-12 General error 

-13 Diskette write protected 

-14 Diskette was changed 

-15 Unknown device 

-16 Bad sector (during verify) 

-17 Insert diskette (for connected drive) 

Example 

move.w #1,-(sp) Read a sector 
move.w #0,-(sp) Page zero 
move.w #0,-(sp) Track zero 
move.w #1,-(sp) Sector one 
move.w #1,-(sp) Drive B 
clr.1 -(sp) 
move.l #buffer,-(sp) 
move.w #8,-(sp) floprd 


trap #14 
add. lL: $20 ,3sp 
LSet do 

bmi error 


burtfer dscb-512 


Did @rror occur? 
yes 


Buitfer for -a sector 


1 es. 
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9 Flopwr write diskette sector 


C: int Floprd(buffer, filler, dev, sector, track, side, 
count) 
long buffer, filler; 
int dev,sector,track,side,count; 


Assembler: 


move.w count,-—(sp) 
move.w side,-(sp) 
move.w track,-(sp) 
move.w sector,-(sp) 
move.w dev,-(sp) 
Gly: «£Sp) 

move.l buffer,-(sp) 
move.w #9,-—(sp) 
trap #14 

add.l #20,sp 


One or more sectors can be written to disk with this XBIOS function. The 
parameters have the same meaning as for the Floprd function. The function 
returns an error code which has the same meaning as for reading sectors. 


Example: 
move.w #3,-—-(sp) Write three sectors 
move.w #0,-—(sp) Side zero 
move.w #7,-—(sp) Track seven 
move.w #1,-(sp) Sector one 
move.w #0,-(sp) Drive A 
CL, “={sp) 
move.l #buffer,-(sp) Address of the buffer 
move.w #9,-—(sp) flopwr 
trap #14 
add.1l #20,sp 
Est do Did an error occur? 
bmi error yes 
DVULLer- is. 37512 Buffer for three sectors 
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10 Flopfmt format diskette 


CG: int Flopfmt (buffer; filler, dev, spt, track, side, 
interleave, magic, virgin) 
long buffer, filler, magic; 
int’ ‘dev;-spt; track, side, “interleave, virgin; 


Assembler: 
move.w virgin, -(sp) 
move ;:1 magic, - (sp) 
move.w interleave, -(sp) 
move.w side,-(sp) 
move.w track,-(sp) 
move.w spt,-(sp) 
move.w dev,-—(sp) 


Chek) (3p) 
move.l buffer,-(sp) 
move.w #10,-(sp) 
trap #14 

add.l1 #26,sp 


This routine serves to format a track on the diskette. The parameters have 
the following meanings: 


virgin: The sectors are formatted with this value. The 
standard value is $E5ES. The high nibble of each byte 
may not contain the value $F. 


magic: The constant $87654321 must be used as magic or 
formatting will be stopped. 


interleave: Determines in which order the sectors on the disk will 
be written, usually one. 


side: Selects the disk side (0 or 1). 

track: The number of the track to be formatted (0-79). 
spt: Sectors per track, normally 9. 

dev: The drive, O for A and 1 for B. 


es) 
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TE ‘. 


filler: Unused long word. 


buffer: Buffer for the track data; for 9 sectors per track the 
buffer mst be at least 8K large. 


The function returns an error code as its result. The value -16, bad sectors, 
means that data in some sectors could not be read back correctly. In this 
case the buffer contains a list of bad sectors (word data, terminated by 
zero). You can format these again or mark the sectors as bad. 


Example: 
move.w #SE5E5,-(sp) Initial data 
move.l #$87654321,-(sp) magic 
move.w #1,-(sp) interleave 
move.w #0,-(sp) Side 0 
move.w #/79,-(sp) LEack.72 
move.w #9,-(sp) 9 sector per track 
move.w #0,-(sp) drive A 
elr. i: 9° tsp) 
move.w #buffer,-(sp) 
move.w #10,-(sp) £lLopimt 
trap #14 
add.l #26,sp 
Est do 
bmi error 

buffer as.b. 52000 8K buffer 

11 Unused 
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12 Midiws write string to MIDI interface 


Ce - YOld Midawetcount,, pur) 
ane Count; 
Long: pir: 


Assembler: 


move.l ptr,—{sp) 
move.w count,-(sp) 
move.w #12,-(sp) 
trap #14 

addq.1 #8,sp 


With this function it is possible to output a string to the MIDI interface 
(MIDI OUT). The parameter pt r must point to a string, count must contain 
the number of characters to be sent minus 1. 


Example: 
move.l #string,- (sp) Address of the string 
move.w #stringend-string-1l,-(sp) Length 
move.w #12,-(sp) midiws 
trap #14 


addq.1 #8,sp 


string adc. b. MIDE data™ 
Sstringend equ * 
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13 Mfpint initialize MFP format 


C: void Mfpint (number, vector) 
number; 
long vector; 


Line 


Assembler: 


move 


move. 
d W 


move 
Leap 


addq. 


mee § 


WwW 


ES 


VECTOr;— (Sp) 
number, - (sp) 
F135, — (Sp) 
#14 

#8,Sp 


This function initializes an interrupt routine in the MFP. The number of the 
MFP interrupt is in number while vector contains the address of the 
corresponding interrupt routine. The old interrupt vector is overwritten. 


Example: 


move 
move 
move 
trap 


addq. 


busy: 


mui 
.W 
.W 


i 


woUusy,-—= (Sp) Busy interrupt routine 
#0,- (sp) Vector number 0 
#13,—(sp) mfpint 

#14 

#8,Sp 
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14 lorec return record buffer 


C: long Iorec (dev) 
Pot ae 


Assembler: 


move.w dev,-(sp) 
move.w #14,-(sp) 
trap #14 
addq.1 #4,sp 


This function fetches a pointer to a buffer data record for an input device. 
The following input devices can be specified: 


dev Input device 
0 RS-232 
dt Keyboard 
2 MIDI 


The buffer record for an input device has the following layout: 


Long abut Pointer to an input buffer 
Tite ibufsize Size of the input buffer 
eye. ibufhd Head index 

int LETS Talla ndex 

ne aee ibuflow Low water mark 

Inc $5ufn2 High water mark 


The input buffer is a circular buffer; the head index specifies the next write 
position (the buffer 1s filled by an interrupt routine) and the tail index 
specifies from where the buffer can be read. If the head and tail indices are 
the same, the buffer is empty. The low and high marks are used in 
connection with the communications status for the RS-232 (XON/XOFF or 
RTS/CTS). If the input buffer is filled up to the high water mark, the 
sender is informed via XON or CTS that the computer cannot receive any 
more data. When data received by the computer can be processed again, so 
that the buffer contents sink below the low water mark, the transfer 1s 
resumed. 


There is an identically-constructed buffer record for the RS-232 output 
which is located directly behind the input record. 
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The following table contains the data for all devices: 


BRS~232- 1nput’' RS-252 output. Kevooard.. MIDI 


Address S9DO (S9DE) $942 SA00 
Buffer address S6D0 $7D0 S8D0 $950 
Buffer length $100 $100 $80 $80 
Head index 0 : 0 0 0 

Tail index 0 0 0 0 

Low water mark $40 $40 pal dd 
High water mark 20 SCO $20 al Os 


Head and tail indices are naturally dependent on the current operating mode. _ 
High and low water marks are set at 3/4 and 1/4 of the buffer size. They 
have significance only for XON/XOFF or RTS/CTS in connection with 
RS-232. 


Example: 
move.w #1,-(sp) Buffer record for keyboard 
move.w #14,-(sp) lorec 
trap #14 


addq.l1 #4,sp 


Result: $9F2 
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15 Rsconf set RS-232 configuration 


Ce word -Rsconl 1 baud, “CUT, er, tery “ests ser) 
int David; Ceri, cr; Tet. Csr, Ser; 


Assembler: 

move.w scr,-(sp) 

move.w tsr,-(sp) 

move.w rsr,-(sp) 

move.w ucr,-(sp) 

move.w ctrl,-(sp) 
move.w baud,- (sp) 
move.w #15,-(sp) 

trap #14 


add.l #14,sp 


This XBIOS function serves to configure the RS-232 interface. The 
parameters have the following significance: 


scr: Synchronous Character Register in the MFP 
tsr: Transmitter Status Register in the MFP 
rsr: Receiver Status Register in the MFP 

ucr: USART Control Register in the MFP 

ctrl: Communications parameters 

baud: Baud rate 


See the section on the MFP 68901 for information on the MFP registers. If 
one of the parameters is -1, the previous value is retained. The handshake 


mode can be selected with the ctrl parameter: 


ctrl Meaning 
0 No handshake, default after power-up 
1 XON/ XOFF 
2 RTS/CTS 
3 XON/XOFF and RTS/CTS (not useful) 


The baud parameter contains an indicator for the baud rate: 


baud baud rate 


0 19200 
a3 9600 
Z 4800 
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baud baud rate 


eee ee 


3600 
2400 
2000 
1800 
1200 
600 
300 
200 
150 
134 
110 
fas 
50 


#~-1,-(sp) 
#-—1,-(sp) 
#-1,-(sp) 
Pog Vo) 
#1,-(sp) 

oop (30) 

tLOP ASO) 
#14 
#14,sp 
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Don't change MFP registers 


XON/XOFF 
300 baud 
ESconet 
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16 Keytbl set keyboard table 


Cy dong Keytbionsnitt; snire, capsiock) 
LONG UNSntie, sonic, capes lock: 


Assembler: 


move 
move 
move 
move 
trap 


ok 
re 
ms 
.W 


capslock,-(sp) 
shift, —(sp) 
unSshniLe, (Sp) 
#16,-(sp) 

#14 


add.1l #14,sp 


With this function it is possible to create a new keyboard layout. To do this 
you must pass the address of the new tables which contain the key codes for 
normal keys (without shift), shifted keys, and keys with caps lock. The 
function returns the address of the vector table in which the three keyboard 
table pointers are located. If a table should remain unchanged, -1 must be 
passed as the address. A keyboard table must be 128 bytes long. It is 
addressed via the key scan code and returns the ASCII code of the given 


key. 


Example: 


move. 
Move. 
move. 
move . 


say aS 


addq. 


Sha tt: 


oe ae eo 


unSshn7Ttt: 


#-1,-(sp) Don't change caps lock 
#shift,-—(sp) Shift table 
#unshift,-(sp) Table without shift 
#16,—(sp) 

#14 

#14,sp 
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17 Random return random number 


C: long Random() 


Assembler: 


move.w #17,-(sp) 
trap #14 
addq.l #2,sp 


This function returns a 24-bit random number. Bits 24-31 are zero. With 
each call you receive a different result. After turning on the computer a 
different seed is created. 7 


Example: 
move.w #17,-(sp) random 
trap #14 


addq.l1 #2,sp 


18 Protobt produce boot sector 


C: void Protobt (buffer, serialno,disktype, execflag) 
long buffer, serialno; 
int disktype, execflag; _ 


Assembler: 
move.w execflag,-(sp) 
move.w disktype,-— (sp) 
move.l serialno,-(sp) 
move.l buffer,-(sp) 
move.w #18,-(sp) 
trap #14 


add.l #14,sp 


This function serves to create a boot sector. A boot sector 1s located on track 
O, sector 1 on side O of a diskette and gives the DOS information about the 
disk type. If the boot sector is executable, it can be used to load the 
operating system. With this function you can create a new boot sector, for a 
different disk format or to change an existing boot sector. 
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The parameters: 


execflag: determines if the boot sector is executable. 


O not executable 
1 executable 
—-1 boot sector remains as it was 


The disk type can assume the following values: 


he GN © 


The parameter serialno 1s a 24-bit serial number which is written in the 
boot sector. If the serial number is greater than 24 bits ($01000000), a 
random serial number 1s created (with the above function). A value of -1 


AO Lack, 
A0 track, 
SO Crack, 
SO0vErack, 
Disk type 


Single 
double 
Single 
double 


sided (180 kK) 
sided (360 K) 
Sided (360 K) 
Sided (720 K) 


remains unchanged 


means that the serial number will not be changed. 


The parameter buffer is the address of a 512-byte buffer which contains 
the boot sector or in which the boot sector will be created. 


A boot sector has the following construction: 


Address 40 track SS 


Od 
Fees 
age 
LZ 
13 
L415 
16 

NI cee Be 
Lo 20) 
Zt 
ZLtLo 
24-20 
Fg Se ae | 
2e729 


Branch instruction to boot program if executable 


40 track DS 


24-bit serial number 


"Loader' 
BPS SZ 
Src i 
RES if 
FAT 2 
DIR 64 
SEC 360 
MEDIA} Zoz 
SPF 2 
SPT 9 
SIDE i 
HID 0 


SLOU=oi CHECKSUM 


Dubz 
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BPs: Bytes per sector. The sector size is 512 bytes for all formats 


spc: Sectors per cluster. The number of sectors which are combined 
into one block by the DOS, 2 sectors equals 1K 


RES: | Number of reserved disk sectors,including the boot sector. 

FAT: The number of file allocation tables on the disk. 

DIR: The maximum number of directory entries. 

SEC: The total number of sectors on the disk. 

MEDIA: Media descriptor byte, not used by the ST-BIOS. 

spr: | Number of sectors in each FAT. 

spt: | Number of sectors per track. 

SIDE: Number of sides of the diskette. 

HID: Number of hidden sectors on the disk. 
The boot sector is compatible with MS-DOS 2.x. This is why all 16-bit 
words are stored in 8086 format (first low byte, then high byte). If the 
checksum of the whole boot sector is $1234, the sector is executable. In this 


case the boot program 1s located at address 30. 


This program adapts an existing boot sector for 80 tracks, double sided. 


Example: 
move.w #-1,-(sp) Don't change executability 
move.w #3,-(sp) 80 tracks DS 
move... ¢-1L,— (3p) Don't change serial number 
move.l #buffer,- (sp) 
move.w #18,-(sp) DECEGDE 
trap #14 


add.l #14,sp 


DUETSr «Ss bose 
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19 Flopver verify diskette sector 


C: int Flopver (buffer, filler,dev,sector,track, side,count) 
long buffer, filler; 
int dev; Sector, track, side; count: 


Assembler: 
move.w count,-(sp) 
move.w side,-(sp) 
move.w track,-(sp) 
move.w sector,-(sp) 
move.w dev,-(sp) 


Civ. (Sn) 
move.l buffer,-(sp) 
move.w #19,-(sp) 
trap #14 

a0 & $ilo, Sp 


This function verifies one or more sectors on the disk. The sectors are read 
from the disk and compared with the buffer contents in memory. The 
parameters are the same as for reading and wniting sectors. If the sector and 
buffer contents agree, the result will be zero. If an error occurs, an error 
number will be returned in DO (see Read sector for error codes). On an 
error, the buffer will contain a list of bad sectors (16-bit values) terminated 
by a zero word. If Rwabs was used to write the sectors and if fverify 
($444) is set, the sectors will automatically be verified after they are written. 


Example: 
move.w #1,-(sp) A sector 
move.w #0,-(sp) Side zero 
move.w #39,-(sp) Track: 39 
move.w #1,-(sp) Sector 1 
move.w #0,-(sp) Drive A 


eir.l- {sp} 
move.l #buffer,-(sp) Buffer address 


move.w #19,-(sp) flopver 
trap #14 

add.l #16,sp 

cSt do Error: 
bmi error 
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20 Scrdmp output screen dump 


Ce Void -Scramp () 


Assembler: 


move.w #20,-(sp) 
trap #14 
addq.l #2,sp 


This function sends a hardcopy of the screen to a connected printer. The 
previously-set printer parameters ("desktop Printer setup’) are used. You 
can also perform this function by simultaneously pressing the ALT and— 
HELP keys or from the desktop through "Print Screen" from the "Options" 
menu. 


Example: 
move.w #20,-(sp) Hardcopy 
Erep #14 Call XBIOS 


addq.1l #2,sp 


21 Cursconf set cursor configuration 


Clank Curscont (fiunetion, ’ rate) eo 
Ant: Function, Tate; 


Assembler: 


move.w rate,-(sp) 
move.w function,-(sp) 
move.w #21,-(sp) 

trap #14 

addq.l #6,sp 


This XBIOS function serves to set the cursor function. The parameter 
function can have a value from 0-5, which have the following meanings: 


function meaning 
0 Disable cursor 
1 Enable cursor 
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function meaning 


Z Flashing cursor 

3 Steady cursor 

4 Set cursor flash rate 
oe Get cursor flash rate 


You can use this function to set whether the cursor 1s visible, and whether it 
is flashing or steady. The XBIOS function returns a result only if you fetch 
the old baud rate. The unit of the flash frequency is dependent on the screen 
frequency: It 1s 70 Hz for a monochrome monitor or 50 Hz for a color 
monitor. You can set a new flash rate with function number 5. You need 
only use the parameter rate if you want to pass a new flash rate. 


Example: 
move.w #20,-(sp) 20/70 seconds 
move.w #4,—-(sp) Set flash rate 
move.w #21,-(sp) curscont 
trap #14 


addgq.1l #6,sp 


22 Settime set clock time and date 


C: void Settime (time) 
long time; 


Assembler: 


move.l time,- (sp) 
move.w #22,-(sp) 
trap #14 

add.l  #6,sp 


This function is used to set the clock time and date. The time is passed in the 


lower word of time and the date in the upper word. The time and date are 
coded as follows: 


bits O0O- 4 Seconds in two-second increments 
bits 5-10 Minutes 

PLCs Biat> Hours 

bits 16-20 Day 1-31 
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bits 21-24 Month 1-12 
bits 25-31 Year 0-119(minus offset 1980) 


Example: 


move.l #%1011001100000100000000000000,-(sp) 
move.w #22,-(sp) ' gettime 

trap #14 

addq.1l #6,sp 


This call sets the date to the 16th of September, 1985, and the clock time to 
8 o'clock. 


23 Gettime return clock time and date 


C: long Gettime () 


Assembler: 


move.w #23,-(sp) 
trap #14 
addq.l #2,sp 


This function returns the current date and clock time in the following format: 


bits O- 4 Seconds in two-second increments 
bits 5-10 Minutes 

bits -ii-15..Houre 

bits 16-20 Day 1-31 

bits 21-24 Month 1-12 

bits 25-31 Year (minus offset 1980) 


Example: 
move.w #23,-(sp) gettime 
trap #14 
addq.1l #2,sp 
move.l d0,time Save time and date 
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24 Bioskeys restore keyboard table 


C: void Bioskeys () 


Assembler: 


move.w #24,-(sp) 
trap #14 
addq.1 #2,sp 


If you have selected a new keyboard layout with the XBIOS function 16, 
keytbl, this function will restore the standard BIOS keyboard layout. You 
can call this function, for example, before exiting a program of your own 
which changed the keyboard layout. 


Example: 
move.w #24,-(sp) bioskeys 
trap #14 


addq.l #2,sp 


25 Ikbdws intelligent keyboard send 


C: void Ikbdws (number, pointer) 
int number; 
long pointer; 


Assembler: 


move.l pointer,-(sp) 
move.w number,-(sp) 
move.w #25,-(sp) 
trap #14 

addq.1l #8,sp 


This XBIOS function serves to transmit commands to the keyboard 
processor (intelligent keyboard). The parameter pointer is the address of a 
string to be sent, number is the length of a string minus 1. 
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Example: 
move.l #string,-(sp) Address of the string 
move.w #strend-string-1,-(sp) Length minus 1 
move.w #25,-—(sp) ikbdws 
trap #14 


addq.l1 #8,sp 


string AG D. “Seu eI. 
strend equ * 


26 Jdisint disable interrupts on MFP 


Cs VoL) SJaLsint-iniimber) 
int number; 


Assembler: 


move.w number,-(sp) 
move .w #26,-(sp) 
trap #14 

addq.l #4,sp 


This function makes it possible to selectively disable interrupts on the MFP 
68901. The parameter is the MFP interrupt number (0-15). The significance — 
of the individual interrupts is described in the section on interrupts. 


Example: 
move.w #10,-(sp) Disable RS-232 transmitter interrupt 
move.w #26,-— (sp) Disable interrupt 
trap #14 


addq.l #4,sp 
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27 Jenabint enable interrupts on MFP 


C: void Jenabint (number) 
int number; 


Assembler: 


move.w number,-(sp) 
move.w #27,-(sp) 
trap #14 

addq.1 #4,sp 


This function can be used to re-enable an interrupt on the MFP. The 
parameter 1s again the number of the interrupt, 0-15. 


Example: 
move.w #12,-(sp) Enable RS-232 receiver interrupt 
move.w #27,-(sp) Enable interrupt 
trap #14 


addq.1 #4,sp 


28 Giaccess access GI sound chip 


C: char Giaccess(data, register) 
char data; 
int register; 


Assembler: 


move.w #register,-(sp) 
move.w #data,-(sp) 
move.w #28,-(sp) 

trap #14 

addq.1l #6,sp 


This function allows access to the GI sound chip registers. register must 


contain the register number of the sound chip (0-15). The meaning of the 
individual registers is given in the hardware description of the sound chip. 
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Bit 7 of the register number determines whether the specified register will be 
written or read: 


Bit 7 0O: Read 
1: Write 


When writing, an 8-bit value is passed in data; when reading, the function 
returns the contents of the corresponding register. 


Example: 
move.w #$80+3,-(sp) Write register 3 
move.w #$50,-(sp) Value to write 
move.w #28,-(sp). 
trap #14 


addq.l #6,sp 


29 Offgibit reset Port A GI sound chip 


Cr VOL Offa 2 (bi Chamber) 
Int brtniumber-: 


Assembler: 


ove.w #bitnumber,-—(sp) 
iove.w #29,-(sp) 
“xap #14 

ida.1l #4,sp 


~1t of port A of the sound chip can ve se'-stively set with this function 
Port A 1s an 8-bit output port in which the indiviauai o.1, ° >> the 
wing function: 


ohe Select disk side 0/side 1 
ake Select drive A 
ais Select drive B 


0 
- 
Ze 
31t 3: RS-232 RIS. (Request To Send) 
4: RS-232 DTR (Data Terminal Ready) 
= Centronics strobe 

6 General Purpose Output 

7 unused 
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Example: 
move.w #4,-(sp) PIR O2t 
move.w #29,-(sp) offgibit 
trap #14 


addq.1l #4,sp 


30 Ongibit clear Port A of GI sound chip 


ae Cr? void ongibiat (bi tnumber) 
Lint Ditnumber-; 


Assembler: 


move.w #bitnumber,-(sp) 
move.w #30,-(sp) 

trap #14 

addq.1l #4,sp 


This function is the counterpart of the previous function. With this it is 
possible to clear a bit of port A in the sound chip. 


Example: 
= move.w #4,-(sp) i ae oo 
move.w #30,- (sp) ong bit 
trap #14 


addq.1l #4,sp 


2h ERIS ey ISSA RRL E NE e @ alana 
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31 Xbtimer start MFP timer 


C: void Xbtimer(timer, control, data, vector) 
int. Tamer, “cont ro., «Gata; 
long vector; 


Assembler: 
move.l vector,-(sp) 
move.w data,-(sp) 
move.w control,-(sp) 
move.w timer,-(sp) 
move.w #31,-(sp) 
trap #14 


add.l #12,sp 


This function allows you to start a timer in the MFP 68901 and assign an 
interrupt routine to it. timer is the number of the timer in the MFP: 


Tame eA SS Oe - “ame re sd FD Parmer oe ee eae re eS 


The parameters data and control are the values placed in the control and 
data registers of the timer (see the hardware description of the MFP 68901). 


The parameter vector 1s the address of the interrupt routine which will be 
executed when the timer runs out. The four timers in the MFP are already 
partly used by the operating system: “ 


Timer A: Reserved for the end user 

Timer B: Horizontal blank counter 

Timer C: 200 Hz system timer 

Timer D: RS-232 baud rate generator (interrupt vector free) 

Example: 

move.l #vector,-(sp) Interrupt routine 
move.w data,-(sp) Data and 
move.w control,-(sp) Control registers 
move.w #0,-(sp) Timer A 
move.w #31,-(Ssp) xbtimer 
trap #14 


a0Gdis “fiz ssp 
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32 Dosound set sound parameters 


Ce void Dosound (pornter) 
long pointer; 


Assembler: 


move.l pointer,-(sp) 
move.w #32,-(sp) 
trap #14 

addq.1 #6,sp 


This function allows for easy sound processing. The parameter pointer 
must point to a string of sound commands. The following commands can be 
used: 


Commands $00-$0F 
These commands are interpreted as register numbers of the sound 
chip. A byte following this is loaded into the corresponding register. 


Command $80 
An argument follows this command which will be loaded into a 
temporary register. 


Command $81 
Three arguments must follow this command. The first argument is the 
number of the sound chip register in which the contents of the 
temporary register will be loaded. The second argument is a two's- 
complement value which will be added to the temporary register. The 
third argument contains an end criterion. The end is reached when the 
content of the temporary register 1s equal to the end criterion. 


Commands $82-$FF 
One argument follows each of these commands. If this argument 1s 
zero, the sound processing is halted. Otherwise this argument 
specifies the number of timer ticks (2Oms, 50Hz) until the next sound 


processing. 
Example: 
move.l #pointer,-(sp) Pointer to sound command 
MOVE .W #32, —(Sp) dosound 
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trap #14 
addq.l #6,sp 


pointer Foden © yey 6 rap 3 See BPG | 2 ae 


33 Setprt set printer configuration 


Ct Void -Setpre(coniig) 
Le COontiLa: 


Assembler: 


move .w coniig,—(sp) 
move.w #33,-(sp) 
tran #14 

addq.1 #4,sp 


This function allows the printer configuration to be read or changed. If 
config contains the value -1, the current value is returned, otherwise the 
value is accepted as the new printer configuration. The printer configuration 
is a bit vector with the following meaning: 


Bit number 0 - 
0 matrix printer daisy-wheel 
1 monochrome printer color printer 
2 Atari printer Epson printer 
5 Test mode Quality mode 
4 Centronics port RS-232 port 
5 Continuous paper Single-sheet 
6-14 reserved 
ae always 0 
Example 
move.w #%000100,-(sp) Epson printer 
move.w #33,-(sp) setprt 
trap #14 


addq.l #4,sp 
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34 Kbdvbase return keyboard vector table 


C: long Kbdvbase() 


Assembler: 


move.w #34,-(sp) 
trap #14 
addq.1 #2,sp 


This XBIOS function returns a pointer to a vector table which contains the 
address of routines which process the data from the keyboard processor. 
The table is constructed as follows: 


long midivec MIDI anput 

long vkbderr Keyboard error 
long vmiderr MIDI error 

long statvec IKBD Status 

long mousevec Mouse routines 
long clockvec Clock time routine 
long joyvec Joystick routines 
long midisys MIDI system vector 
long ikbdsys IKBD system vector 


The parameter midivec points to a routine which writes data received from 
the MIDI input (byte in DQ) to the MIDI buffer. 


The parameters vkbderr and vmiderr are called when an overflow is 
signaled by the keyboard or MIDI ACIA. 


The routines statvec, mousevec, clockvec, and joyvec process the data 
packages which come from the keyboard ACIA. A pointer to the packages 
received is passed to these routines in DO. The mouse vector is used by 
GEM. If you want to use your own routine, you must terminate it with RTS 
and processing time may take no longer than one millisecond. 


The remaining routines midisys and ikbdsys are called when there is a 
character in the present ACIA. midisys holds the character and jumps to 
midivec; ikbdsys gets the data package from the ACIA, and branches to 
the abovementioned routines. 
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Example: 
move.w #34,-(sp) kbdvbase 
trap #14 


addq.l #2,sp 


We get $DCC as the result. The vector field contains the following values: 


midivec SPCZCEZ/SEB70 

vkbderr SFEZB8E/SE871C (RTS) 
vmiderr PPCZUOE GOL (RTS) 
statvec SFC230A/$8198 (RTS) 
mousevec SFD02C2/$16150 
clockvec». SFCID1I2Z/ S7BAD 

joyvec SFC230A/$8198 (RTS) 
midisys SFC284A/S$86D8 

ikbdsys SFC285A/S$86E8 


35 Kbrate set keyboard repeat rate 


C: int Kbrate(delay, repeat) 
int delay, repeat; 


Assembler: 


move. 
nove: 
move. 


Lrap 


addq. 


a 


repeat,-—(sp) 
delay,-(sp) 
To, SA SD) 
#14 

#6,Sp 


The keyboard repeat can be controlled with this function. The parameter 
delay specifies the delay time after a key is pressed before the key will 
automatically be repeated. The parameter repeat determines the time span 
after which the key will be repeated again. These values can be changed 
from the desktop by means of the two slide controllers on the control panel. 
The times are based on the 50 Hz system clock. If -1 1s specified for one of 
the parameters, the corresponding value is not set. The function returns the 
previous values as the result; bits 0-7 contain the repeat value and bits 
8-15 the value of delay. 
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Example: 


move 
move 
move 
trap 


addq. 


Result: DO = $0B03 


-W 
-W 
-W #35,-(sp) 


al 


#-1,- (sp) 


#-1,-—(sp) 


#14 
#6,Sp 


36 Prtblik 
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Read old values 


kbrate 


output block to printer 


C: void Prtblk (parameter) 


long parameter; 


Assembler: 


move.l parameter, -—(sp) 
move.w #36,-(sp) 


trap 


#14 


addq.1 #6,sp 


This function resembles and is used by the function Scrdmp (20). The 
function expects a parameter list, however, whose address is passed to it. 
This list 1s constructed as follows: 


long 
int 
Ine 
chene 
Fe he 
2G 
int 
phone 
long 
big he 
roa ee 
long 


DLEDEC 
offset 
width 
height 
left 
right 
scrres 
dstres 
colpal 
type 
DOL 
masks 


Address 


of the screen RAM 


Screen width 
Screen height 


Screen resolution (0, 1, or 2) 


Printer 
Address 
Printer 
Printer 
Pointer 


resolution (0 or 1) 

of the color palette 

type (0-3) 

port (0=Centronics, 1=RS-232) 
to half-tone mask 
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Example: 
move.l #parameter,-—(sp) Address of the parameter block 
move.w #36,-(sp) Prtbik 
trap #14 


addq.l #6,sp 


parameter dc.l 


37 Vsynec wait for video 


Ot Vora Vsyne¢) 


Assembler: 


move.w #37,-(sp) 
trap #14 
adda. l #2;Ssp 


This function waits for the next picture return. It can be used to synchronize 
graphic outputs with the beam return, for example. 


Example: 
move .w #37,-(sp) wait for vsync 
trap #14 


addq.l1 #2,sp 
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38 Supexec set supervisor execution 


C: void Supexec (address) 
long address; 


Assembler: 


move.l address,-(sp) 
move.w #38,-(sp) 
trap #14 

addq.1 #6,sp 


A routine can be executed in supervisor mode with Supexec. 
Example: 

move.l #address,-(sp) 

move.w #38,-(sp) 

trap #14 

addq.l #6,sp 


address move.l $400,00 


39 Puntaes disable AES 


C: void Puntaes() 


Assembler: 


move.w #39,-(sp) 
trap #14 
addq.l #2,sp 


The AES can be disabled with this function, provided it is not in ROM. 
Example: 
move.w #39,-(sp) 


Erap #14 
addq.1l #2,sp 
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64 Blitmode read and alter blitter 


C: int Blitmode (flag) 
int flag; 


Assembler: 


move.w flag,-(sp) 
move.w #64,-(sp) 
trap #14 

addq.l #4,sp 


This function lets you read and change an available blitter's configuration. 
Blitmode also lets you determine whether a blitter exists in the system (bit 
1) and whether it is usable (bit 0). The ST reads the current configuration 
when flag has a value of -1 (Oxffff). The result is a bitmask. Each bit 
represents the following: 


Bit number 0 z 
0 Bist -cperatzon Blit_ operation 
through software through hardware 
1. No blitter available Blitter available 
2-14 Undefined, reserved 
ths: Always 0 


When a blitter is available, you can determine whether blit operations can be _ 
performed by software or by the blitter. This is established by clearing o1 
setting bit 0. 


Bit number 0 iL 
0 BLit—operatton Blit_ operation 
through software through hardware 
1-14 Undefined, reserved 
LS Always 0 
Example: 
move #-1, (sp) set configuration 
move #64, -(sp) blitmode 
trap #14 
addq.1 #4,sp 
best #1,da0 is blitter on hand? 
beq NO ae no 
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bset #0,da0 


move ao, = (Sp) blit operation through hardware 
move #64, -(sp) blit-mode 

trap #14 

addq.l1 #4, sp 

no bli: 

rts 


The above sample program tests for an onboard blitter. If this is the case, 
the system bit O displays blit operations through hardware (the blitter). The 
test, once set to hardware, won't ignore onboard blitters in the system. 


| ~~ By setting the blit mode, this should call the configuration, and the bits 1-14 
should be taken over. They are reserved for further graphic functions or 
graphic chips. 
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3.4 The Graphics 


Next to the high processing speed and the large memory available, the 
graphics capability is certainly the most fascinating aspect of the ST. With 
the standard monochrome monitor and the resolution of 640x400 points, it 
creates a whole new price/performance class for itself. But also in the color 
resolution the ST can display 16 colors with 320x200 screen points. 


In this chapter we want to explain how the graphics are organized and how 

you can create fast and effective graphics without using the GEM graphics 

package, which is rather complicated for beginners. The ST offers thy 
assembler and C programmer very useful routines which don't exactly make 
graphics programming child's play, but which can take away a good deal of 
the programming work. Unfortunately, some of these functions are so 

comprehensive that a detailed description would exceed the scope of this 

book. We have therefore had to limit ourselves to the simpler, but no less 

interesting functions. 


These graphics routines are called in a very elegant manner. The software 
developers have made use of the fact that there are two groups of opcodes in 
the 68000 which the 68000 does not "understand" and which generate a 
trap, or software interrupt, when they are encountered in a program. These 
are the two groups of opcodes which begin with $Axxx and $Fxxx. In the 
ST, the $Axxx opcode trap is used in order to access the graphics routines. 
The trap handler, the program called by the trap, checks the lowest byte of. 
the command" to see what value it has. Values between zero and $F are 
permissible here. This gives a total of 16 graphics routines, which should 
first be presented in an overview. Later we will talk about the actual 
commands in detail. 


SA000 Determine address of required variable range 
SA001 Set point on the screen 

SA002 Determine color of a screen point 
SA003 Draw a line on the screen 

SA004 Draw a horizontal line (very fast!) 
SA005 Fill rectangle with color 

SA006 Fill polygon line by line 

SA007 Bit block transfer 

SA008 Text block transfer 

SA009 Enable mouse cursor 

SAQOOA Disable mouse cursor 
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SAO0O0B Change mouse cursor form 
SAQ0OC Clear sprite 

SA0O0D Enable sprite 

SAQDOE Copy raster form 

TAOUUE Contour: £2)  tFiocd: t114) 


These routines are the ground work for the hardware-dependent part of 
GEM. All GEM graphic and text output is performed by the routines of the 
$Axxx opcodes. The set of A-opcodes are very useful in games. In games 
windows are needed only in the rarest cases. Another important point is the 
speed of the line A-instructions. Using the graphic routines directly is 
clearly faster than if the output is handled by GEM. Before we describe the 
individual commands in detail, we will take a brief look at the construction 
of graphics in the various graphic modes of the ST. 


Immediately after turning the ST on, an area of 32K bytes 1s initialized at the 
upper memory border as the video RAM. In normal operation this results in 
addresses $78000 to $7FFFF or $F8000 to $FFFFF acting as the screen 
RAM. This video RAM can be viewed as a window in the ST. The 
following description is a simplification of the features of the 260ST with 
"only" 512K. 


We will start with the simplest mode, the 640x400 mode. In this case each 
set of 80 bytes, or better, each set of 40 words forms one screen line. The 
word with the lowest address is displayed on the left edge of the screen, the 
additional words are displayed in order from left to right. Within a word, 
the highest-order bit lies at the left and the lowest-order bit at the nght. 


With this data, any point on the screen can be easily controlled or read. For 
example, to set the first screen point, the value $8000 must be written into 
memory location $78000. There is one small limitation to this area. The 
position of ST screen RAM can be easily moved. For this reason, it is 
usually more advantageous to set the point with the "A" function $A001. 
Function $A001 assumes an X-Y coordinate.system with origin in the upper 
left-hand corner, and determines the position of the video RAM itself in 
order to set the point at the proper screen location. 


In this resolution mode, each screen point is represented by a bit. If the bit 
is set, the point appears dark, or bright if the inverse display mode is 
selected in color palette register 0. The screen consists of only one bit plane. 
Different colors cannot be represented with just one plane, however. This is 
why when the resolution increases in the color modes, the number of 
displayable colors decreases. 
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Figure 3.4-1 LO-RES-MODE (0) 
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Four colors are possible in the 640x200 resolution mode. In this mode, two 
contiguous memory words form a single logical entity. The color of a point 
is determined by the value of the two corresponding bits in the two words. 
If both bits are zero, the background color results. Therefore two sequential 
words are used together for pixel representation. For the colors, however, 
all odd words belong to a plane. The second plane is made up of the even 
words. In this mode, there are two planes available. 


Things become quite colorful in the mode with "only" 320x200 points. In 
this operating mode, 4 contiguous memory words form one entity which 
determines the color of the 16 pixels. To stick to the example we used 
before: in order to set the point in the upper left-hand corner, the topmost 
bits of words $78000, $78002, $78004, and $78006 must be manipulated. 
The desired color results from the bit pattern in the words. 


It naturally requires some computer time to set a point in the desired color, 
independent of the mode. All of this work is handled by the $A001 routine, 
however. This routine sets all of the pertaining bits for the desired color in 
the current resolution. Naturally, all four planes are present in this mode. 
The first plane, keeping to our example, made up of the words at address 
$7FO00, $7F008, $7FO10, ..., and the other planes are composed of the 
other addresses correspondingly. 


Another point to be clarified concerns the fonts or character sets. Since the 


ST does not have a text mode, only a graphics mode, the text output is 
created in high-resolution graphics. There are three different fonts built into 
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the ST. You can load additional fonts from disk. Each font has a header 
which contains important information about the displayable characters. 
Since the important data are contained in the font header, there are unusually 
few limits for display. The characters can be arbitrarily high or wide. The 
age of the 8x8 matrix for character output is over. It 1s even possible to get 
cursive, bold, true proportional or other type on the screen. 


The three built-in fonts are monospaced fonts, meaning they have a fixed 
defined size in pixels and a defined pitch. The smallest font has a matrix of 
6x6. With a resolution of 640x400 points, 66 lines of 106 characters each 
can be displayed. This font is only accessible for output under GEM, not 
for output under TOS, and 1s used in the output of the directory in the icon 
form, for example. The next-largest type 1s composed of 8x8 points. This 
type is used when a color monitor is connected to the ST, while the third 
and largest font is used for the normal black-and-white mode. This font 
uses a matrix of 8x16 points. 


Figure 3.4-2 MEDIUM-RES-MODE (1) 


Video-RAM [TTT LOTT 


The exact layout of the font header is found under command $A008, which 
represents a very versatile text output which goes far beyond what is 
possible with the routine of the BIOS and GEMDOS. 


Finally, we must clarify some of the terms which will come up often in the 


following descriptions, whose meanings may not be so clear. These are the 
terms Contr] array, Intin array, Intout array, Ptsin array and Ptsout array. 
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These arrays are mainly used by GEM to pass parameters to individual 
GEM functions or to store results from these functions. But line-A 
functions use parts of these arrays to pass parameters also. The arrays are 
defined in memory as data areas, whereby each element 1 in the array consists 
of 2 bytes. 


For GEM functions, the Contr] array always contains the number desired in 
the first element (Contrl(0)). This parameter is not used by the line-A 
commands, however. Contrl(1) contains the number of XY coordinates 
required for the function. These coordinates must be placed in the Ptsin 
array before the call. The element Contrl(2) is not supplied before the call. 
After the call it contains the number of XY coordinates in the Ptsout array. 


Contrl(3) specifies how many parameters will be passed to the function in 


the Intin array, while Contrl(4) contains the number of parameters in the 
Intout array after the call. The additional parameters of the Contrl array are 
not relevant for users of the line A. 


Unfortunately, not all of the A opcode parameters can be in these arrays. 
For this reason there 1s another memory area which used as a variable area 
for (almost) all graphic outputs. The functions and uses of these over 50 
variables are in a table at the end of this chapter. Important variables are also 
explained in conjunction with the functions requiring them. 


By the way, you should be aware that registers DO to D2 and AO to A2 are 


changed by calling the functions. Important values contained in these 
registers should be saved before a call. 


Figure 3.4-3 HI-RES-MODE (2) 


Video Screen 


399 


Color Number 


Video-RAM 
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$A000 Initialize 


Initialize is really the wrong expression for this function. After the call, the 
addresses of the more important data areas are returned in registers DO and 
AO to A2. This function does not require input parameters. 


The program is informed of the starting address of the line-A variables in 
DO and AO. After the call, Al points to a table with three addresses. These 
three addresses are the starting address of the three system font headers. 
Register A2 points to a table with the starting addresses of the 16 line-A 
routines. 


This opcode destroys (at least) the contents of registers DO to D2 and AO to 
A2. Important values should be saved before the call. 


$A001 PUT PIXEL 


This opcode sets a point at the coordinates specified by the coordinates in 
Ptsin(0) and Ptsin(1). The color is passed in Intin(0), Ptsin(0) 
contains X-coordinate, Ptsin(1) the Y-coordinate. 


The coordinate system used has its origin in the upper left corner. The 
possible range of the X and Y coordinates is naturally set according to the 
graphic mode enabled. Overflows in the X range are not handled as errors. 
Instead, the Y coordinate is simply incremented by the appropriate amount. 
No output is made if the Y range is exceeded. 


The color in Intin(0) is dependent on the mode used. When driving the 
monochrome monitor, only bit zero of the value of Intin(0) is evaluated. 


$A002 GET PIXEL 
The color of a pixel can be determined with this opcode. As with $A001, 


the XY coordinates are passed in Ptsin(0) and Ptsin(1); the color value 
is returned in the D0 register. 
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$A003 LINE 


With the LINE opcode a line can be drawn between the points with 
coordinates xl,yl and x2,y2. The parameters for this function are not 
passed via the parameter arrays, but must be transferred to the line-A 
variables before the call. The variables used are: 


pot = xl coordinate 


- ¥1 = yl coordinate 
_X2 = x2 coordinate 
pa = yl coordinate 


_FG BP 1 = Plane 1 (all three modes) 
FG BP 2 = Plane 2 (640x200, 320x200) 
_FG BP 3 = Piane-s..tonly .320x200) 
JEG BP A = Pieness AOnty 220x200) 
_LN MASK = Bit pattern of the line 

For example: SFFFF = filled 


$CCCC = broken 
_WRT_MOD = Determines the write mode 
_LSTLIN = This variable should be set to -1 (SFFFF) 


One point to be noted for some applications is the fact that when drawing a 
line, the highest bit of the line bit pattern is always set on the left screen 
edge. The line is always drawn from left to right and from top to bottom, 
not from x1l,y1l to x2,y2. 


Range overflows are handled as for PUT PIXEL. If an attempt is made to 
draw a line from 0,0 to 650,50, a line is actually drawn from, 0,0 to 
639,48. The "remainder" results in an additional line from 0,49 to 10,50. 


A total of four different write modes, with values 0 to 3, are available for 
drawing lines. With write mode zero, the original bit pattern "under" the line 
is erased and the bit pattern determined by _LN MASK is put in its place 
(replace mode). In the transparent mode (_ WRT MOD=1), the background, the 
old bit pattern, is ORed with the new line pattern so only additional points 
are set. In the XOR mode (_WRT_MOD=2), the background and the line 
pattern are exclusive-ored. The last mode (_ WRT _MOD=3) is the so-called 
"Inverse transparent mode." As in the transparent mode, it involves an OR 
combination of the foreground and background data, in which the 
foreground data, the bit pattern determined by LN MASK, are inverted 
before the OR operation. 
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$4004 HORIZONTAL LINE 


This function draws a line from x1,y1 to x2,y1. Drawing a horizontal line 1s 
significantly faster than when a line must be drawn diagonally. Diagonal 
lines are also created with this function, in which the line is divided into 
multiple horizontal lines segments. The parameters are entered directly into 
the required variables. 


9: = xl coordinate 
fe 3 = yl coordinate 
X2 = x2 coordinate 


_FG BP 1 = Plane 1 (all three modes) 

_FG BP 2 = Plane 2 (640x200, 320x200) 
_FG BP 3 = Plane 3 (only 320x200) 

_FG BP 4 = Plane -4 (only 320x200) 

_WRT MOD = Determines the write mode 

_patptr = Pointer to the line pattern to use 
_patmsk = “Mask™ for the line pattern 


The valid values in wRT MoD also lie between 0 and 3 for this call. The 
contents of the variable patptr is the address at which the desired line 
pattern or fill pattern is located. The H-line function is very well-suited to 
creating filled surfaces. The variable _patmsk plays an important role in 
this. The number of 16-bit values at the address in_patptr is dependent 
on the its value. If, forexample, patmsk contains the value 5, six 16-bit 
values should be located at the address in _patptr as the line pattern. Ifa 
horizontal line with the Y-coordinate value zero is to be drawn, the first bit 
pattern is taken as the line pattern. The second word is taken as the pattern 
for a line drawn at Y-coordinate 1, and so on. The pattern for a line with 
Y-coordinate 6 is again determined by the first value in the bit table. In this 
manner, very complex fill patterns can be created with relatively little effort. 


$A005 FILLED RECTANGLE 


The opcode $A005 represents an extension, or more exactly a special use, 
of opcode $A004. It is used to created filled rectangles. The essential 
parameters are the coordinates of the upper left and lower night corners of 
the of the rectangle. 


Jat = xl coordinate, left upper 
Pe! | = yl coordinate 
_X2 | x2 coordinate, right lower 
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2X2 = y2 coordinate 

_FG BP 1 = Plane 1 (all three modes) 
_FG BP_2 = Plane 2 (640x200, 320x200) 
_FG BP 3 = Plane 3 (only 320x200) 
_FG BP_3 = Plane 4 (only 320x200) 


_WRT MOD = Determines the write mode 
-pabptr = Pointer to the fill pattern used 
_patmsk = "Mask" for the fill pattern 
CULE = Clipping flag 


_XMN CLIP = X minimum for clipping 
_XMX CLIP = X maximum for clipping 
_YMN CLIP = Y minimum for clipping 
_YMX CLIP = Y maximum for clipping 


We have already explained all of the variables except the "clipping" 
variables. What is clipping? Clipping creates extracts or clippings of the 
total picture. If the clipping flag is set to one (or any value not equal to 
zero), the rectangle, drawn by $A005, is displayed only in the area defined 
by the clipping-area variables. An example may explain this behavior better: 

The values 100,100 and 200,200 are specified as the coordinates. The clip 
flag is 1 and the clip variables contain the values 150,150 for xMN_ CLIP and 
YMN CLIP as well as 300,300 for xMx CLIP and yMx CLIP. The value 
$FFFF will be chosen as the fill value for all of the lines. With these values, 

the rectangle will have the coordinate 150,150 as the upper left corner and 
200,200 as the lower right. The "missing" area is not drawn because of the 
clip specifications. Clearing the clip flag draws the rectangle in the originally 
desired size. 


$A006 FILLED POLYGON 


$A006 is also an extension of $A004. Areas can be filled with a pattern with 
this function. The entire surface is not filled with the call: just one raster line 
is filled, a horizontal line with a width of one point. The result is that there 
are significantly more options for influencing the fill pattern. 


The necessary variables are: 


PCsin = Array with the XY coordinates 
Contr L(l) Number of coordinate pairs 
es) yl coordinate | 
2FG_ BP 1” = Pieane 1 (ali~Ehree moaces) 

_FG BP 2 = Plane 2 (640x200, 320x200) 
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—FG BP’ 3 = Plane 3 {only 320x200) 

FG’ BP :3 = Plane 4 -(only 320x200) 

_WRT MOD = Determines the write mode 
_patptr = Pointer to the fill pattern used 
_patmsk = "Mask" for the fill pattern 
eee = Clipping flag 

_XMN CLIP = X minimum for clipping 

_XMX CLIP = X maximum for clipping 

_YMN CLIP = Y minimum for clipping 

_YMX CLIP = Y maximum for clipping 


Basically, all of the parameters here are to be set exactly as they might be for 
a call to $A005. Only the first three coordinates are different. The XY 
coordinates are stored in the Ptsin array. It is important you specify the 
start coordinate again as the last coordinate as well. In order to fill a triangle, 
you must, for example, enter the coordinates (320,100), (120,300), 
(520,300), and (320,100). The number of effective coordinate pairs, three 
in our example, must be placed in Contr1(1), the second element of the 
array. With a call to the $A006 function you must also specify the 
Y-coordinate of the line to be drawn. Naturally you can fill all Y-coordinates 
from 0 to 399 (0 to 199 in the color modes) in order. But it is faster to find 
the largest and smallest of the XY values and call the function with only 
these as the range. 


$A007 BITBLT 


The BITBLock Transfer function copies a square source range into a target 
area. The source range can combine with a raster. Source and target range 
can be combined with 16 different logical operations. You can have these at 
any address. Normally it 1s at least the target area of video RAM; but it can 
also be copied within the screen or from an unused part of memory to 
another. If a blitter is onboard the ST, BITBLT uses hardware. 


BITBLT is used by the line-A functions TEXTBLT and COPY RASTER 
FORM, as well as the VDI functions Copy Raster Opaque (vro_cpyfm) and 
Copy Raster Transparent (vrt cpyfm). BITBLT's versatility involves the 
parameters used with the function call. These parameters are source, 
destination and pattern; information about the number of bitplanes (color or 
b/w) used; and logical operations combining source and destination. The 
data stands in a 76-byte parameter block, whose function address must be 
given through register A6. The parameter block looks like this: 
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Offset Length Name 


10 
14 
16 
18 
22 
24 
26 
28 
30 
JZ 
36 
38 
40 
42 
46 
48 
50 
OZ 


Sars es Se Bo 22 Ss SS Sa SF 


Se ae ee Ce 


N 
= 


s width Pixel width of range being edited 


2 heightPixel height of range being edited cow’ 


planes 
Eg-col 
bg col 
op tab 
s_ xmin 
Ss ymin 
Ss form 
s nxwd 
s nxln 
s nxpl 
d xmin 
d ymin 
d form 
d nxwd 
d nxln 
d nxpl 
p_addr 
p nxin 
p_nxpl 
p_mask 
fo tler 


Number of bit planes 

Foreground color 

Background color 

Logical operation 

Source upper left X-coordinate 
Source upper left Y-coordinate 
Source starting address 

Byte offset of next source line wesw 
Byte offset of next source line 

Byte offset of next source color plane 
Destination upper left X-coordinate 
Destination upper left Y-coordinate 
Start address through destination 
Byte offset of next destination word 
Byte offset of next destination line 
Next destination color plane 

Start address of pattern 

Byte offset of next raster line 

Byte offset of next color plane 
Raster height (raster index mask) 
Used internally by BITBLT 


When destination and/or source ranges appear on the screen, the following 


values are used: 


Resolution 
Bitplanes 
d_form/s_ form 
d_nxwd/s_ nxwd 
d nxln/s.mxin 
donxp l/s nxpt 


320*200 640*200 640*400 

4 2 u 
screen address 

8 4 ate 

160 160 80 

Z Z 2 


Here are the 16 logical operations used in combining source and desination: 


Operation Function 


0 D' 
1 D' 
2 Dh 
3 D' 


= 0 

= 5S &D 
S & 

= 5S 


~D 


Set destination to background color 


Replace Mode 


216 


m Cl <2 


Abacus Software Atari ST Internals 


4 D' = ~S &€ D Erase Mode 
5 D' = D 

6 109 ee a XOR Mode 

7 eS - ST eD 

8 Dm a 

9 Ys me ee ee 

10 D' = ~D 

aie D* = S$ | =D 

TZ D' = ~§S 

i Oke D*' = ~§ | D 

14 ye Ge 1D) 

io Dt = Set destination to foreground color 


S=Source; D=Destination range before operation; D '=Destination range 
after the operation; &=logical AND; | =logical OR; *=XOR (exclusive OR); 
—=Inversion. 


Four such logical operations are given for BITBLT, addressed in the 
equation op = 2 * fg + bg. op is the used logical operation (0-3, 
relative to op tab). fg is the foreground color and bg is the background 
color. 


$A008 TEXTBLT 


A character from any desired text font can be printed at any graphic position 
with the TEXT BLock Transfer function. In addition, the form of the 
character can be changed. The character can be displayed in italics, 
boldface, outlines, enlarged, or rotated. These things cannot be achieved 
with the "normal" character outputs via the BIOS or GEMDOS. TXTBLT 
often stands as the basic structure of all text output under VDI 
(v_gtext,etc.). 


For the correct use of this function, a large number of parameters must be 
set and controlled. A rather complicated program must be written in order to 
output text with this function. If the additional options are not absolutely 
necessary, it is advisable not to use this function. But decide for yourself. 


Before we produce a character on the screen, we must first concern 
ourselves with the organization of the fonts. We must take an especially 


close look at the font header because the font is described in detail by the 
information contained in it. 


2) We 
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A font basically consists of four sets of data: font header, font data, 
character offset table and horizontal offset table. The font header contains 
general data about the font, such as its name and size, the number of 
characters it contains, and various other aspects. This information takes up a 
total of 88 bytes. The font data contains the bit pattern of the existing 
displayable characters. These data are organized to save as much space as 
possible. 


In order to be able to better describe the organization, we will imagine a font 
with only two characters, such as "A" and "B". These characters are to be 
displayed in a 9x9 matrix. The font data are now in memory so that the bit 
pattern of the top scan line of the ''A" 1s stored starting at a word boundary. 


Since our font is 9 pixels = 9 bits wide, one byte 1s completely used, but 
only the top bit of the following byte. 7 bits must be wasted if the top scan 
line of the "B" is also to begin on a word boundary. This is not so, 
however, and the first scan line of the "B" starts with bit 6 of the second 
byte of the font data. Only the data of the second and further scan lines 
always start on a word boundary. In this manner, almost no bits are wasted 
in the font. Only the start of the scan lines of the first character actually 
begin on a word boundary; all other scan lines can begin at any bit position. 


Because of this space-saving storage, the position of each character within 
the font must be calculated. The calculation of the scan-line positions is 
possible through the character offset table. This table contains one entry for 
each displayable character. For our example, such a table would contain the 
entries $0000, $0009, $0012. Through the direction of this table, it is 


possible to create true proportional type on the screen since the width of ~ 


each character can be calculated. One subtracts the entry of the character to 
be displayed from the entry of the next character. The last entry is present so 
that the width of the last character can also be determined, although it is not 
assigned to a character. 


In addition to the character offset table there is the horizontal offset table. 
This table is not used by most of the fonts, however. The fonts present in 
the ST do not use all the possibilities of this table either. If this table were 
present, it would contain a positive or negative offset value for each 
character, in order to shift the character to the nght or left during output. 


At the end of the description of the font construction are the meanings of the 
variables in the font header. 
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Bytes 
Bytes 
Bytes 
Bytes 
Bytes 
Bytes 


Bytes 
Bytes 


Bytes 
Bytes 


Bytes 


Bytes 
Bytes 


Bytes 


Bytes 


Bytes 


Bytes 72-75 


a5 
20-7 
30-39 
40-49 


S04. 
I2ro3 


34755 
56-2 } 


es ahs be, 


60-61 
62-65 


54-55 


65-67 


oe haat aS 


‘Font. .toent i. rites: 


FOnt. Size: in -polnes 


: Thickening. 


: Skewing mask. 
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A number which describes the 
l=system font 
(point iS a measure used 


font. 


in typesetting). 


: The name of the font as an ASCII string. 

: Lowest ASCII value of displayable characters. 
: Highest ASCII value of displayable characters. 
: Relative distances 


Sie tone ascent... halt, 


descent, and bottom line from the base line. 


: Width of the broadest character in the font. 
>: Width of the broadest character cell. The cell 


is always at least one pixel wider than the 
actual character so that two characters next 
to each other are separated from each other. 


>: Linker offset. 
: Right offset. 


The two offset values are used 
for displaying the font in italics (skewing). 
If a character is to be displayed 


in boldface, this variable is used. 


: Underline. Contains line height in pixels. 
: Lightening mask. 


"Light™ characters are found 
on the desktop when an option on a pull-down 
menu is unavailable. This light grey character 
COnsists’ “olf masking thei DitSs with eEhe 
lightening mask. Usually the value is $5555. 
As before, only for displaying 
characters in italics. 


>: Flag. Bit 0 is set if a system font is used. 


Bit 1° must be- set “i= the horizontal. offset 
table is present. 

Bit 2 is the so-called byte-swap flag. If it 
is set, the bytes in memory are in 68000 
format (low byte-high byte). A cleared swap 
flag signals that the data is in INTEL format, 
reversed in memory. With this bit the fonts 
from the IBM version of GEM can be used on the 
ST and vice versa. 

Bit 3 is set if the width of all characters in 
the font is equal. 


:* Pointer to “the horizontal. cifset “tanple or 


aero. 


>: Pointer to the character offset table. 
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Bytes 76-79 
Bytes 80-81 


Bytes 82-83 


Bytes 84-87 


: Pointer. to the font data. 
> Form width. This variable contains the 


widths of all the characters. The 
represents the length of the scan lines 
of the characters and thereby the start 
next line. 


: Form height. This variable contains the 


of. scan lines for. this. font: 


: Contain a pointer to the next font. 


sum of 
value 
oy me: BADE 
of the 


number 


After so much talk, we should now list the parameters which must be noted 
or prepared for the $A008 opcode. 


_WRT_MODE = Write mode 

_TEXT FG = Text foreground color 

_ TEXT BG = Text background color 

_FBASE = Pointer to the start of the font data 
_FWIDTH = Width of the font 

_SOURCEX = X-coordinate of the char in the font 
ZSQURCEY = Y-coordinate of the char in the font 
_DESTX = X-coordinate of the char on the screen 
*DESTY = Y-coordinate of the char on the screen 
_DELX = Width of the character in pixels 
»DELY = Height of the character in pixels 
_STYLE = Bit-wise coded flag for special effects 
_LITEMASK = Bit pattern used for "lightening" 
_SKEWMASK = Bit pattern used for skewing 

_WEIGHT = Factor for character enlargement 
Or = Right offset of the char for skewing 
od OFF = Left offset of the char for skewing 

_ SCALE = Flag for scaling 

_XACC_DDA = Accumulator for scaling 

_DDA_INC = Scaling factor 

_ TSCLSTS = Scaling direction flag 

.,CHUP = Character rotation vector 

_MONO STATUS = Flag for monospaced type 

_scrtchp = Pointer to buffer for effects 

Pee Von 2) eh = Of iset. scaling puLrter in. serechp 


AS you can see, an enormous number of variables are evaluated for the 
output of graphic text. Here we can go into only the essential (and those we 
explored) variables. 
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The write mode allows the output of characters in the four known modes, 
replace, OR, XOR, and inverse OR. The variable TEXT FG is in 
connection with first four write modes. They form the foreground color 
used for display. The background color TEXT BG plays a role only with the 
16 additional modes. It is clear that the additional modes are relevant only in 
connection with a color screen. 


The variables FBASE and FWIDTH are set according to the desired font. 
You can find the start of the font data from the header of the desired font 
(bytes 76-79 in the header). FWIDTH must be loaded with the contents of 
the bytes 80 and 81 of the header. 


The parameter _SOURCEX determines which character you output. It should 
contain the ASCII value of the desired character. The parameter SOURCEY 
is usually zero because the character 1s to be generated from the top to the 
bottom scan line. 


The parameter DELX can be calculated as the width of the character in 
which the entry in the character offset table of the desired character is 
subtracted from the next entry. The result is the width of the character in 
pixels. DELY must be loaded with the value of byte 82-83 of the header. 


The STYLE is something special. Here you can specify if characters should 
be displayed normally or changed. The possible changes are boldface 
(thicken, bit 0), shading (lighten, bit 1), italic (bit 2), and outline (bit 4). 
The given change is enabled by setting the corresponding bit. Another 
change is scaling. The size of a character can be changed through scaling. 
Unfortunately, characters can only be enlarged on the ST. 


If the scaling flag is cleared (zero), the character is displayed in its original 
size. The T scusts flag determines if the font is to be reduced or 
enlarged. A value other than zero must be placed here for enlarging. 
_DDA_INC should contain the value of the enlargement or reduction. An 
enlargement could be produced only with a value of $FFFF. 


Another interesting variable is _cHupP. With the help of this variable, 
characters can be rotated on the screen. The angle must be given in the range 
O to 360 degrees in tenths of a degree. A restriction must also be made for 
this function. Usable results are obtainable only with rotations by 90 
degrees. The values are $0000 for normal, $0384 for 90-degree rotation, 
$0708 (upside-down type), and $0A8C for 270 degrees. 
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To work with the effects, scrchp must contain a pointer to a buffer in 
which TEXTBLT can store temporary values. The exact size of this buffer 
is not known, but we always found a buffer of 1K to be sufficient. Another 
buffer must be specified for enlargement (_scrpt2). An offset is passed as 
a parameter which refers to the start of the scrtchp buffer. A value of $40 
proved to be sufficient here. — 


$A009 SHOW MOUSE 


Calling this opcode enables the display of the mouse cursor. The cursor 
follows the mouse when it is moved. If the mouse cursor is disabled, the 
mouse can be used in programs which abandon the user interface GEM. 
This option is particularly useful for games. 


The parameters required are passed in the Intin and Contrl arrays. 
Contrl1(1) should be cleared before the call and contr1(3) set to one. 
Intin(0) has a special significance. The routine for managing the mouse 
cursor counts the number of calls to remove and enable the cursor. If the 
cursor 1S disabled twice, two calls must be made to re-enable it before it will 
actually appear on the screen. This behavior can be changed by clearing 
Intin(0). With this parameter the cursor is immediately set independent of 
the number of previous HIDE CURSOR calls. If the value in Intin(0) is 
not equal to zero the actually required number of $A009 calls must be made 
in order to make the cursor visible. 


$A00A HIDE CURSOR 


This functions hides the cursor. If this function is called repeatedly, the 
number is recorded by the operating system and determines the number of 
calls of SHOW CURSOR before the cursor actually appears. 


$A00B TRANSFORM MOUSE 


Is the arrow unsuited as a mouse cursor for games? Simply make your own 
cursor. How would it be if a little car moved across the screen instead of an 
arrow? The opcode $AOOB gives your fantasy free reign, at least as far as it 
concerns the mouse cursor. 


The parameters must be passed in the Int in array. A total of 34 words are 
necessary. The following table lists the uses and possible values: 
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Intin(3) Mask color index, normally 0 

Intin (4) Data color index; normality <i 

Intin(5) to Intin(20) contain -16 words of-the cursor-mask 
Tnhtini2Zi) to Intam (56), contazn 16. words of cursor data 


The form of the cursor is determined by the cursor data. Each 1 in the data 
creates a point on the screen. If a cursor is placed over a letter or pattern on 
the screen, the border between the cursor and the background cannot be 
determined. The mask enters at this point. Each set bit in the mask clears the 
background at the given location. This draws a light border around the 
cursor. Look at the normal cursor in order to see the operation of the mask. 


$A00C UNDRAW SPRITE 


This opcode is related to $A00D, DRAW SPRITE. The ST actually has no 
hardware sprites like the Commodore 64. ST sprites are organized purely in 
software. Each sprite is 16x16 pixels large. One example of an ST sprite is 
the mouse cursor. It is created with this function. 


To clear a previously-drawn sprite, the address of a buffer in which the 
background was saved when the sprite was drawn 1s passed in register A2. 
The opcode simply transfers the contents of the background buffer to the 
right spot on the screen. The buffer itself must be 64 bytes large for each 
plane. Another 10 bytes are used, independent of the number of planes. For 
monochrome display, the buffer is a total of 74 bytes long, while in the 
320x200 pixel resolution (for planes), it is 4x64+10=266 bytes large. 


$A00D DRAW SPRITE 


This function draws the desired sprite on the screen. Parameters must be 
passed in the DO, D1, AO, and A2 registers. 


DO and D1 contain the X and Y-coordinates of the position of the sprite on 
the screen, called the hot spot. AO is a pointer to the so-called sprite 
definition block and A2 contains the address of the sprite buffer in which 
the background will be saved for erasing the sprite later. 

The sprite definition block must have the following construction: 


Word 1 : X offset to hot spot 
Word 2 : Y offset to hot spot 
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er nn 


Word 3 : Format flag 0=VDI format, -1=XOR format 
Word 4. Background =color, £9) 
Word 5 : Foreground color (fg) 


Following this are 32 words which contain the sprite pattern. The pattern 
must be in memory in the following order: 


Word 6 : Background pattern of the top line 
Word 7 : Foreground pattern of the top line 


Word 8 : Background pattern of the second line 
Word 9 : Foreground pattern of the second line 
etc. 


The information in the format flag has the following significance: 


VDI .Format 


foo bg Result 
0 0 The background appears 
0 1 The color in word 4 appears 
1 0 The color in word 5 appears 
1 1 The color in word 5 appears 

XOR Format 

Go" bg Result 
0 0 The background appears 
0 1 The color in word 4 appears 
1 0 Th fb bit XORs the pixel on the screen 
1 ‘8 The color in word 5 appears 


S$AN0E COPY RASTER FORM 


Arbitrary areas of the screen can be copied with the $AO0OE opcode. Not 
only areas within the screen, but also from the screen into free RAM, and 
even more important, from the RAM to the screen. Even complete screen 
pages can be copied very quickly with the COPY RASTER opcode. The 
name RASTER FORM does express one limitation of the function, 
however. Each raster form to be copied must begin on a word boundary and 
must be a set of words. 


The parameters are quite numerous and are passed in the Contrl, Ptsin, 


and Intin arrays. In addition, two "memory form definition" blocks must 
be in memory for COPY RASTER. We will start with the MFD blocks. 
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Since a copy operation must always have a source and a destination, one 
block describes the source memory range and the second describes the 
destination. Each block consists of 10 words. The address of the memory 
described by the block is contained in the first two words. The third word 
specifies the height of the form in pixels. Word 4 determines the width of 
the form in words. Word 6 should be set to 1 and word 7 specifies the 
number of planes of which the form is composed. The remaining words 
should be set to zero because they are reserved for future extensions. 


Necessary parameters for COPY RASTER: 


INTIN[0] BIt."0=3 
Opaque:Logical operation; Transparent: 
Writing mode (see $A007, BITBLT) 
Bit 4 = 0: no pattern used; 

1: pattern used 


INTIN [1] Transparent only: 1 bit color index 
INTIN [2] Transparent only: 0 bit color index 
PTSIN[0] Upper left source X-coordinate 
PTSIN{1} Upper left source Y-coordinate 

PTSIN [2] Lower right source X-coordinate 
PYTSIN(34 Lower right source Y-coordinate 
PTSIN [4] Upper left destination X-coordinate 
PTSIN[5] Upper left destination Y-coordinate 
PTSIN [6] Lower right destination X-coordinate 
PTSIN [7] Lower right destination Y-coordinate 


CONTRL[7+8] Address source MFDB 
CONTRL[9+10] Address destination MFDB 
~patptr Pattern pointer (when used) 
_multifill 0 = pattern has one plane 
1 = pattern has several planes 
_COPYTRAN 0 = opaque 
N-plane source and n-plane destination 
1 = transparent i 
Source with a plane copied through all 
destination planes (transparent). 


Memory Form Definition Block (MFDB) design: 


Offset Size Meaning 


0 long Pointer to raster image 
4 word Raster width in pixels 
6 word Raster height in pixels 
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8 word Raster width in words 
10 word Format flag 
0 = device-specific 
1 = number of bit planes 
12 word Number of bit planes 
14 word Reserved — 


When the COPY RASTER function is used, the raster image in 
device-specific format must be laid out first. (Standard format arranges the 
bitplanes one after the other, instead of nesting them by words). 


A few remarks about the words "opaque" and "transparent: Opaque 
copying simply combines the corresponding color planes of source and 
destination, as well as the resulting raster, though a logical operation with a 
value from 0 to 15 (see also $A007, BITBLT). Here the number of color 
planes in source and destination must match, or else the function stops. 
Opaque copying doesn't require the values in INTIN[1] and INTIN[2]. 
Transparent copying copies a source range containing a single color plane to 
a multicolor destination range. The source range consists of only two 
different colors, represented by bits 0 and 1. You can determine which color 
appears in the source range pixels. Give the corresponding color numbers in 
INTIN[1] and INTIN[2]. 


In INTIN[O] writing mode is used instead of the logical operations: 


INTIN[0O] Writing mode 


1. Replace mode 

Zz Transparent mode 

3 XOR mode 

4 Reverse transparent mode 


These procedures serve when a source range is only two colors, and when a 
monochrome as well as a color screen are used. Monochrome copying 
naturally displays in black and white; color screens can use the two colors 
from the available palette. The diskette icons from the Desktop are copied 
using these procedures. 


Copy Raster Opaque is identical in the other respects to the VDI function 


109, vro_cpyfm, while Copy Raster Transparent corresponds to the VDI 
function 121, vrt_cpyfm. 
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$A00F CONTOUR FILL (FLOOD FILL) 


The line-A opcode $AOOF is not documented by Atari at present. However, 
when you look at the program with the help of a disassembler, you can see 
a $A00x opcode execute. It's much more difficult to determine WHICH 
function the $AOOF opcode performs. Now, this is our mystery to be 
unraveled. $AOOF calls a fill routine. This fill is identical to the VDI 
function 103 Contour Fill. 


Contour Fill requires an XY coordinate and a mode word for parameters. 
The coordinates are stored in PTSIN(O) and PTSIN(1), the mode word in 
INTIN(O). The mode word means the following: If we have a positive 
value, this value is established as the color value. An area is then filled with 
either the border color or the given color. If the value is negative, the fill 1s 
limited to the color of the starting point. 


Some of the variables important to this command are clipping, write mode, 
pattern pointer and pattern mask without multifill. 


3.4.1 An overview of the "line-A" variables 


After the initialization $4000, DO and AO contain the address of a variable 
area which contains more than 50 line-A variables. The essential variables 
have been described along with the various calls, but not the location of the 
variables within the variable block. We will present this list shortly. When 
naming the variables we have remained with the names used in the official 
Atari documentation. 


Offset is the value which must be given to access the value register relative. 
Variables supplied with a question mark could not be definitively explained. 


eee 
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Offset Name 


60 
62 
64 


66 


68 


v_planes 
v_lin wr 
Concert 
intain 
Ptsin 
Intout 
PTSour 

: 2G. Bee 
an BE ag 
UEGZBE 3 
GBP <4 
_LSTLIN 
_LN MASK 
_WRT_ MODE 


_Y2 
{patcper 
_patmsk 
SOULEA EI 
=e hee 

_XMN CLIP 
_YMN CLIP 
JAMA CLIP 
AMX CELP 
_XACC DDA 


_DDA_INC 


JT SCiusts 


Size 


word 
word 
long 
long 
long 
long 
long 
word 
word 
word 
word 
word 
word 
word 


word 
word 
word 
word 
long 


word 
word 
word 
word 
word 
word 
word 


word 


word 


word 
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Function 


Number of planes 

Bytes per scan line 

Pointer to the Contrl array 

Pointer to the Intin array 

Pointer to the Ptsin array 

Pointer to the Intout array 

Pointer to the Ptsout array 

Plane 0 color value 

Plane 1 color value 

Plane 2 color value 

Plane 3 color value 

Should be -1 (SFFFF) (7?) 

Line pattern for $A003 

Write mode (0=write mode 
1l=transparent 
2=XOR mode 
3=Inverse trans.) 

X1-coordinate 

Yl-coordinate 

X2-coordinate 

Y2-coordinate 

Fill pattern pointer 

(see SA004) 

Fill pattern "mask" 

(see $SA004) 

O=fill pattern for one plane 

1=fill pattern for multiplane 

O=no clipping (see $A005) 

unequal to 0=clipping 

define upper left corner of 

the visible clipping area and 

define lower right corner of 

the visible area for clipping 

Should be set to $8000 before 

Gach call fo TRYST (7) 

Enlargement/reduction factor 

SFFFF for enlargement, 

reduction doesn't work (?) 

O=reduction (?) 

l=enlargement 
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70 _MONO STATUS word 1=no proportional font 
O=proportional type or width 
of character changed by bold 
oraatalics 

ae _SOURCEX word -X-coordinate of char in font 

74 _SOURCEY word Yecoord of: chariin font °(0) 


Note: SOURCEX is the value of the character from the 
horizontal offset table (HOT) and can be calculated with 
the formula SOURCEX = HOT-element (ASCII value minus 
FIRST ADE). The variable FIRST ADE is contained in bytes 
36,37 of the font header (see example) 


76 _DESTX word X-position of char on screen 
78 _DESTY word Y-position of char on screen 
80 _DELX word Character width 
82 _DELY word Character height 


Note: DELX can be calculated with the formula DELX = 
SOURCEX+1 minus SOURCEX (see $A008). DELY is the value 
FORM height from bytes 82,83 of the font header. 


84 _FBASE song -Pointer to start of font data 

88 _FWIDTH long Width of font form 

90 _STYLE word Special effects flag 
(see $A008) 

Ge _LITEMASK word Mask for shading © 

94 _SKEWMASK word Mask for italic type 

96 _ WEIGHT word Number of bits by which the 
character will be expanded 

98 eRcOre word Offset for italic type 

100 _L OFF word Offset for italic type 


Note: The above five variables should be loaded with the 
corresponding values from the font header. 


102 _ SCALE word 0=no scaling 
l=scaling (enlarge/reduce) 
104 JCHUP word Angle for character rotation 


O=normal char representation 
$384=rotated 90 degrees 
$708=rotated 180 degrees 
SA8C=rotated 270 degrees 
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106 
108 


a Ot Bs 


114 
116 


_TEXT_FG word 
Tsertchp long 
SSBCrprezZ word 
_ TEXT. BG word 

COPYTRAN word 
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Text display foreground color 
Buffer address required for 
creating special text effects 
Offset of the enlargement 
buffer in the scrtchp buffer 
Background color for text rep 


(?) 


3.4.2 Examples for using the line-A opcodes 


To make your first experiments with the line-A opcodes easier, here are a 
few examples to serve you as a Starting point. In the first example, $A001 
sets a point is set on the screen with $A001, $A002 sets the point's color. 


KKK KK KKK KKK KKK KEK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK Kk KKK 


Demo of S$A000,SA001 and SA002 functions 


KEK K KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK 


* 


THEI 
Ptsin 
init 
setpix 


getpix 


start: 


move 


Eat 
Intin(a0),a3 
Ptsin(a0),a4 


#300, (a4) 
#100,2 (a4) 


#1, (a3) 


setpix 


#300, (a4) 
#100, 2 (a4) 
getpix 


call SAOOO 
address of Intin-arrays 
address of Ptsin-arrays 


X coordinate 
Y coordinate 


Color set; pixel: set 
O erases pixel 


set pixel 
X coordinate 


y coordinate 
get color value 


qdO now contains color value 
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A monochrome monitor requires only the color values zero and one. Other 
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values can be entered when working in one of the color modes, however. 


The next example shows how a triangle can be drawn on the screen with the 


function FILLED POLYGON. 


Kak KKK KKK KKK KKK KKK KKK KK Kkh KKK KKK KKK Kk Kk Kk Kk Kk Kk kkk kkk kkk 


* 


Conc? | 
ptsin 


fg bpl 
fg bp2 
Lg .DpS 
tg bp4 
wrt _mod 


yl 


Pacer 
patmsk 
multiat4i11. 
"o8 th ©. 

xmn clip 
ymn_ clip 
xmx Clip 
ymx clip 


2 oa S s 
polygon 


a006 - filled polygon 


KEK KK KKK KKK KEK KKK KKK KKK KKK KKK KKEKKKEKEKKEKKEKKKKKKKKKKK 


equ 
equ 


equ 
equ 
equ 
equ 
equ 


equ 


equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 


$a000 
$a006 


AALE 


#1,fg bpl (a0) 
fg_bp2 (a0) 
fg bp3(a0) 
fg_bp4 (a0) 
#2,wrt_mod(a0) 


#fill,patptr (a0) 
#4, patmsk (a0) 
muLes 1111 (a0) 
clip(a0) 
contcrltav) -as 


i | 


get variable block address 
from AO 


set colors for 
monochrome only 


replace mode 


pointer to the fill pattern 
four fill patterns 

only one plane (monochrome) 
no clipping 

Contrl array address from A6é 
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loop 


Loop. 


1 age 


tab: 


addq.l 
move.w 


move.l 
move.l 
move .w 
move .wW 
dbra 


move .w 
move .w 
move.l 


Q, 
Q 
Zi =z € 


Q 
Q 
a a a > 


#2,a6 
#3, (a6) 


ptsin(a0),a6é 
#tab,a5 
#8,¢3 
(a5) +, (a6) + 
d3, loop 


#100,da3 
d3,yl (a0) 
aQ,-(sp) 


polygon 


(sp)+,a0 
1,03 
F301 3 
loopl 


%$1100110011001100 
SOLTOLIOLIOLIOL IG 
$0011001100110011 
$1001100110011001 


320, 100 
Leg, 200 
720 ou 
3207100 


woe 


Ao > Contritt) 
the XY pair in Ptsin 


Ptsin array address from A6 
Coordinate table 
receive 8 coordinates 


first scanline 
ryon 2. 
store address variable block 


fill scanline, destroy AO 


restore AO 

calculate next scanline 
last scanline? 

no, next scanline 
subroutine all done 
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The next example shows how to enable the mouse © 
cursor form. The example waits for a key press before 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KK KKK KKK KKK KKES © 


* show mouse - transform mouse 


KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKEKKKKKKKKKKKKKKK KKH > 


intin equ 
LAL ca equ 
show _mouse equ 


transmouse equ 


Start: 


Loop: 


maus: 
maske: 


Initio 
Intin(taod).a5 
#0,6(a5) 

1 6445) 
#0 aS 
maus,a4 
#15,d0 
(a4) +, (as) + 
d0, loop 
transmouse 
bh os he oe 


Intin(a0),a0 
(a0) 


show_mouse 


address Intir 


bi 5 eae rs ae OS 
PALA A245 


hoo Rte ma Bg be 9 
data for new 
32 words = 16é 


transfer Intin 


and set for: 


Number Hide 
now the new | 


subroutine 


%0000000110000000 
$0000011111100000 
$0001111111111000 
gC Si a Re Fe Us se a 
Oe tO Ss pe Wg 
SlLTILOOT 2 TOOL 
SLLPIOOL LT ELO0TL Ts 


Fs 
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daten: 


Peee ee 


eae ee ee ee eae 


< 


PILI LOOT E200 Tih 
%0000001111000000 
%0000001111000000 
%0000001111000000 
%0000001111000000 
%0000001111000000 
%0000001111000000 
%$0000000000000000 


%0000000000000000 
%0000000000000000 
%0000000110000000 
%0000011001100000 
%0110000110000110 
%0110000110000110 
$0000000110000000 
%0000000110000000 
%0000000110000000 
%0000000110000000 
%0000000110000000 
%0000000110000000 
%0000000110000000 
%0000000000000000 
%0000000000000000 
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3.5 The Exception Vectors 


The first 1024 bytes of the 68000 processor are reserved for the exception 
vectors. Routines which use exception handling store the addresses they 
require in this range of memory. 


A condition which leads to an exception can come either from the processor 
itself or from the peripheral components and controls units connected to it. 
The interrupts, described in the next section, belong to the class of external 
events. In addition, a so-called bus error can be created externally. 


A bus error can be created by many circumstances. For one, certain memory 
areas can be protected from unauthorized access by it. As you may already 
know, the 68000 can run in one of two operating modes. The operating 
system is driven at the first level, the supervisor mode. The user mode 1s 
intended for user programs. In order that a user program not be able to 
access important system variables as well as the system components in an 
uncontrolled fashion, such an access in the user mode leads to a bus error. 
If such an error occurs, the processor stops execution of the instruction, 
saves the program counter and status register on the stack, and branches to a 
routine, the address of which it fetches from the lowest 1024 bytes of 
memory. In the case of the bus error, the address is at memory location 8 
(one long word). What happens in this routine? 


First the vector number of the interrupt is determined and placed in address 
$3C4. Then the registers will get up to 16 words from the system stack and 
store them. Therein is the address by which the interruption occurred, as 
well as the current system status. In the case of a bus or address error, 
these words contain the address at which the error occurred, as well as the 
type of access (see any 68000 user's manual). As many cherry bombs 
appear on the screen as the interrupt vector number. In the case of a bus 
error, for example, this number is 2. Execution then returns to the GEM 
Desktop. 


The range in which the above information will be stored retains this 
information until the ST is reset. It therefore conveys the complete status of 
the processor until a crash occurs. The data lie at the following addresses: 


$380 contains $12345678 when the following data is valid 


$384 - $3A3 DO - D7 
$3A4 - $3BF AO - AG 
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$3C0 
$3c4 
$3C8 


S3CC =" 83E5 


SSP 


Exception number 


USP 


LG. Words E£rom. Sse 


The following table contains all of the exception vectors. 


Vector number Address Exception vector meaning 
0 $000 Stack pointer after reset 
1 $004 Program counter after reset 
Z $008 Bus error 
‘ S00C Address error 
4 SOLO Tllegal instruction 
5 $014 Division by zero 
6 $018 CHK instruction 
7 SOLC TRAPV instruction 
8 $020 Privilege violation 
9 $024 Trace 

10 $028 Line-A emulator 

ia SO2C Line-F emulator 
12-14 $030-S$038 reserved 

dB: op Rw Uninitialized interrupt 
16-23 $040-S05C reserved 

24 $060 SHUrLLOUS. INTCEELUDt 

ao $064 Level 1 interrupt 

26 $068 Level 2 interrupt 

27 SO6C Level 3 interrupt 

28 070 Level 4 interrupt 

29 $074 Level 5 interrupt 

30 $078 Level 6 interrupt 

a SOTC Level 7 interrupt 

a2 $080 TRAP #0 instruction 

Se: $084 TRAP #1 instruction 

34 $088 TRAP #2 instruction 

SD SO08C TRAP #2. 1nStYuce1on 

36 $090 TRAP #4 instruction 

oF $094 TRAP #5 instruction 

38 $098 TRAP #6 instruction 

39 S09C TRAP #7 instruction 

40 SOAO TRAP #8 instruction 

41 SOA4 TRAP 4S: 2rstruction 

42 SO0A8 TRAP” #10 instruction 

43 SOAC TRAP #11 instruction 
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44 SOBO TRAP #12 instruction 
45 SOB4 TRAP #13 instruction 
46 SOB8 TRAP #14 instruction 
47 SOBC TRAP #15 instruction 
48-63 SOCO-SOFC reserved 
64-255 $100-S3FC User interrupt vectors 


The following vectors are used on the ST: 


Line-A emulator $FC9SCA2 / SFB30 
Line-F emulator SA30E / S3A6AE 
Level 2 interrupt SFCO61E / $64AC 
Level 4 interrupt SFC0634 / $64C2 
TRAP #1 GEMDOS SFC4D48 / SABD6 
TRAP #2 GEM SFE340E / $29B76 
TRAP #13 BIOS SPCO74E../..S$65DC 
TRAP #14 XBIOS SFCO0748 / S$65D6 


The first address refers to the ROM version; the second address is read 
when the operating system is found in RAM. The vector for division by 
zero points to rte and returns directly to the interrupted program. Vectors 
64-79 are reserved for the MFP 68901 interrupts. All other vectors point to 
$FCOA1A/$68A8 which outputs the vector number and ends the program as 
described for the bus error. : 


All of the unused vectors can be used for your own purposes, such as the 
line-F emulator or the 12 unused traps. 
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3.5.1 The line-F emulator 


The ST operating system uses the line-F emulator to replace frequently used 
command sequences with just one command. Since the better part of the 
operating system is written in C, especially the AES, you'll often find a 
sequence at the end of a C subroutine, generated by the compiler: 


Cab (AT) + 

movem.1 (A7)+,Dx-Dy/Ax-Ay 
chem Ao 

fy ts 


This sequence requires 5 words. A 16-bit mask in the movem command 
decides which register will be taken from the stack. Bits 0 - 7 stand for data 
registers DO - D7, and bits 8 - 15 are for the address registers (AO - A7). 
This mask is ORed by the opcode $F000 to shift the second bit to the right, 
and set bit 0. Thus it is possible to get the register contents of D3 - D7 and 
AO - A5, which are used by the C compiler, from the stack. Four words 
will be stored during this procedure. 


If bit O 1s not set in the line-F command, the opcode will be interpreted as a 
pointer in a table, from which the address of a routine will be taken. This 
routine will then branch to the return address previously placed on the stack. 
The opcode must be divisible by 4; e.g., $FO00, $F004, etc., up to $F9CC. 
The jump table resides at S$FEE8BC-$FEF28B or $34B60-$3552F. 


Since the line-F routine contains self-modifying code, it is copied into 
RAM. 
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KAEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK TINE-F emulator 


OOA30E 341F move.w (A7)+,D2 Get status from stack 
OOA310 205F move.l (A7)+,A0 Return address 
OOA312 3218 move.w (A0O)+,D1 Get opcode 
00A314 08010000 | btst #0,D1 Billo set? 
O0A318 6614 bne SA32E Yes 
OOA31A 46C2 move.w D2,SR Set status 
OOA31C 2F08 move.l A0O,-({A7) Return addr. from stack 
OOA31E 02410FFF and.w #SOFFF,D1 Delete bits 12-15 
OOA322 207COOFEE8BC move.l1 #SFEE8BC,A0 Base address of table 
O0OA328 20701000 move.l1 0O(A0,D1.W),AO Get address 
OOA32C 4EDO jmp (AQ) Execute routine 
OOA32E 02410FFE and.w #SOFFE,D1 Delete bits 12-15 and bit 0 
GOAS32.6712 beq SA346 SFOO1, then unlk/rts 
O0A334 E549 isi.w #2,D1 Shift mask 
00A336 007C07000 Ors w #$700,SR Save IPL 7, interrupts 
OOA33A 41FA0008 lea SA344(PC),A0O Register mask address 
OOA33E 3081 move.w D1, (AO) Copy mask in program 
OOA340 588F addq.l #4,A7 Correct stack 
O0OA342 4CDF2000 movem.1 (A7)+,A5 Get register again 
OOA346 46C2 move.w D2,SR Set status 
OOA348 4E5E unlk A6é release local variables 
OOA34A 4E75 rts Return from call 

Bit no. : FEDCBA9876543210 

Opcode : 1111XXXXXXXXXxXxX1 

Register ; AAAAAADDDDD 

54321076543 
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3.5.2 The interrupt structure of the ST 


The interrupt capabilities offered by the 68000 microprocessor are put to 
good use in «:e ST. As you may have already gathered from the hardware 
description of the processor, the processor has seven interrupt levels with 
different priorities. The interrupt mask in the system byte of the status 
register determines which levels can generate an interrupt. An interrupt can 
only be generated by a level higher than the current contents of the mask in 
the status register. A interrupt of a certain priority is communicated to the 
processor by the three interrupt priority level inputs. The following 
assignment results: 


Level IPL 2 1 0 
7 (NMI) ae: 9 eee 6, 
6 Se oa | 
2 Go “8 
4 era. ae 
3 a Oe eo 
Z co 5 aes | 
Bi Le er 6 
0 (Se 


If all three lines are 1 (interrupt level 0), no interrupt is present. Interrupt 
level © 1s the NMI (non-maskable interrupt), which is executed even if the 
interr © mask in the status register contains seven. Which interrupt is 
assign. vhich vector (that is, the address of the routine which will process 
the in. -upt) depends on the peripheral component which generates the 
inter For auto-vectors, the processor itself derives the interrupt number 


from iterrupt level. The following table is used in this process: 

Le Vector number Vector address 

IP 2D $64 

IP 26 $68 

IP Pe S6C 

EF 23 $70 

IP 29 $74 

IP 30 $78 

nm 2 oe S71 
Only pais loan: lis 2eare used on (ie Atal os Acme IPs 
perm: y set toa 1 level so that only levels 2, 4 and 6 are available. The 
results the following assignment: 
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LPi,*2 HBL, horizontal blank, line return 
IPL 4 VBL, vertical blank, picture return 
IPL 6 MFP 68901 


The HPL interrupt is generated on each line return from the video section. It 
is generated every 50 to 64 us depending on the monitor connected 
(monochrome or color). It occurs very often and is normally not permitted 
by an interrupt mask of three. The standard HBL routine therefore only has 
the task of setting the interrupt mask to three if it is zero and allows the HBL 
interrupt so that no more HBL interrupts will occur. One use of the HBL 
interrupt could be for special screen effects. With the help of this routine, 
you know exactly which line of the screen has just been displayed. Of much 
greater importance, however, is the VBL interrupt, which is generated on 
each picture return. This occurs 50, 60, or 70 times per second depending 
on the monitor. 


The vertical blank interrupt (VBL) routine accomplishes a whole set of a 
tasks which must be periodically executed or which concern the screen 
display. When entering the routine, the frame counter frclock ($466) is 
first incremented. Next, a test is made to see if the VBL interrupt is 
software-disabled. This is the case if vblsem ($452) (vertical blank 
semaphore) is zero or negative. In this case the routine is exited immediately 
and execution returns to the interrupted program. Otherwise, all of the 
registers are saved on the stack and the counter _vbclock ($462), which 
counts the executed VBL routines, is incremented. Next, a check 1s made to 
see if a different monitor has been connected in the meantime. If a change 
was made from a monochrome to color monitor, the video shifter 1s 
reprogrammed accordingly. This is necessary because the high screen 
frequency of 70 Hz of the monochrome monitor could damage a color 
monitor. The routine to flash the cursor is called next. If you load a new 
color palette via the appropriate BIOS functions or want to change the 
screen address, this happens here in the VBL routine. Since nothing is 
displayed at this time, a change can be made here without disturbing 
anything else. If colorptr ($45A) is not equal to zero, it is interpreted as 
a pointer to a new color palette, and this is loaded into the video shifter. The 
pointer is then cleared again. If screenptr 1s set, this value is used as the 
new base address of the screen. This takes care of the screen specific 
portions. 


Now the floppy VBL routine is called which, with the help of the write 
protect status, determines if a diskette was changed. An additional task of 
this routine is to deselect the drives after the disk controller has turned the 
drive motor off. 
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Now comes the most interesting part for the programmer, the processing of 
the VBL queue. There is a way to tell the operating system to execute your 
own routines within the VBL interrupt. The maximum number of routines 
possible is in nvbls ($454). This value is normally initialized to 8, but it 
can be increased if required. Address vblqueue ($456) contains a 
pointer to a vector array which contains the (8) addresses of the VBL 
routines. Each address is tested within the VBL routine and the 
corresponding routine executed if the address 1s not zero. 


If you want to install your own VBL routine, check the 8 entries until you 
find one which contains a zero. At this address you can write a pointer to 
your routine which from now on will be executed in every VBL interrupt. 
In all 8 entries are already occupied, you can copy the entries into a free area 
of memory, append the address of your routine, and redirect vblqueue 
to point to the new vector array. Naturally, you must not forget to increment 
vbls, the number of routines, correspondingly. Your routine may change 
all registers with the exception of the USP. 


As soon as the VBL routine is done, the dmpflg ($4EE) is checked. If 
this memory location is zero, a hardcopy of the screen is outputted. The flag 
is set in the keyboard interrupt routine if the keys ALT and HELP are 
pressed at the same time. Finally, the register contents are restored, 
vbl1lsem is released and execution returns to the interrupted routine. 


The MFP 68901 occupies interrupt level six in our previous table. This 
component is in the position to create interrupt vectors on its own. These are 
referred to non-auto vectors in contrast to the auto vectors used above, 
because the processor does not generate the vector itself. In the Atari ST, _ 
the MFP 68901 works as the interrupt controller. It manages the interrupt 
requests of all peripheral components including its own. 


The MFP can manage sixteen interrupts which are prioritized in reference to 
each other, similar to the seven levels of the processor. All MFP interrupts 
appear on level 6 to the 68000, therefore prioritized higher than HBL and 
VBL interrupts. The table on the next page contains the assignments within 
the MFP. 


Level Assignment 
Lo Monochrome monitor detect 
14 RS-232 ring indicator 
is System clock timer A 
12 RS-232 receive buffer full 
11 RS-232 receive error 
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Level Assignment 

10 RS-232 transmit buffer empty 
9 RS-232 transmit error 

8 Line return counter, timer B 
P Floppy controller and DMA 

6 Keyboard and MIDI ACIAs 
Tamer -C 

4 RS-232 baud rate generator, timer D 
5 unused 

2 RewZog Clo 

i: Roxszc2 DCD 

0 Centronics busy 


Not all of these possible interrupt sources are enabled, however. Some 
signals are processed through polling. The following is a description of the 
interrupts which are used by the operating system. 


Level 2, RS-232 CTS, address $FC26B2 / $8540 


This interrupt is generated every time the RS-232 interface is informed via 
the CTS line that a connected receiver is ready to receive additional data. 
The routine then sends the next character from the RS-232 transmit buffer. 


Level 5, Timer C, address $FC2F78 / $8E06 


This timer runs at 200 Hz. The 200 Hz counter at $4BA is first incremented 
in the interrupt routine. The next actions are performed only every fourth 
call to the interrupt routine, that is, only every 20ms (50 Hz). First a routine 
is called which handles the sound processing. Another task of this interrupt 
is the keyboard repeat when a key is pressed and initial repeat. Finally, the 
evt timer routine of GEM is called, which is accessed via vector $400. 


Level 6, Keyboard and Midi, address $FC281C / $86AA 


Two peripheral components are connected to this interrupt level of the MFP, 
the two ACIAs which receive data from the keyboard and the MIDI 
interface. In order to decide which of the two components has requested an 
interrupt, the interrupt request bits in the status registers of the ACIAs are 
tested and the received byte is fetched if required. If it comes from the 
keyboard, the scan code is converted to the ASCII code by means of the 
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keyboard table and written into the receive buffer, which happens 
immediately for MIDI data. Mouse and joystick data also come from the 
keyboard ACIA and are also prepared accordingly. 


Level 9, RS-232 transmit error, address $FC2718 / $85A6 


If an error occurs while sending RS-232 data, this interrupt routine is 
activated. Here the transmitter status register 1s read and the status is saved 
in the RS-232 parameter block. 


Level 10, RS-232 transmit buffer empty, address $FC2666 / ~ 
$84F4 


Each time the MFP has completely outputted a data byte via the RS-232 
interface, it generates this interrupt. It is then ready to send the next byte. If 
data is still in the transmit buffer, the next byte 1s written into the transmit 
register, which can now be shifted out according to the selected baud rate. 


Level 11, RS-232 receive error, address $FC26FA / $8588 


If an error occurs when receiving RS-232 data, this interrupt routine is 
activated. This may involve a parity error or an overflow. The routine only 
clears the receiver status register and then returns. 


Level 12, RS-232 receive buffer full, address $FC2596 / 
$8424 


If the MFP has received a complete byte, this interrupt occurs. Here the 
character can be fetched and written into the receive buffer (if there is still 
room). This routine takes into account the active handshake mode (sending 
XON/XOFF or RTS/CTS). 


The other interrupt possibilities of the MFP are not used, but they can be 


used for your own routines. For example, interrupt level 0, Centronics 
strobe, can be used for buffered printer output. 
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3.6 The Atari ST VT52 Emulator 


There are two options for text output on the ST. You can work with the 
GEMDOS functions by means of TRAP #1 or a direct BIOS call with 
TRAP #13. The other possibility consists of using the VDI functions. 


You have special options for screen control with both variants. We will first 
take a look at output using the normal DOS or BIOS calls. Here a terminal 
of type VTS2, which offers a wide variety of control functions, is emulated 
for screen output. These control characters are prefixed with a special 
character, the escape code. Escape, or ESC for short, has an ASCII code of 
27. Following the escape code is a letter which determines the function, as 
well as additional parameters if required. The following list contains all of 
the control codes and their significance. 


ESC A Cursor up 
This function moves the cursor up one line. If the cursor was already 
on the top line, nothing happens. 


ESC B Cursor down 
This ESC sequence positions the cursor one line down. If the cursor 
is already on the bottom line, nothing happens. 


ESC C Cursor right 
This sequence moves the cursor one column to the right. 


ESC D Cursor left | 
Moves the cursor one position to the left. This function is identical to 
the control code backspace (BS, ASCII code 8). If the cursor is 
already in the first column, nothing happens. 


ESC E Clear Home 
This control sequence clears the entire screen and positions the cursor 
in the upper left corner of the screen (home position). 
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ESC H Cursor home 


With this function you can place the cursor in the upper left corner of 
the screen without erasing the contents of the screen. 


ESC I Cursor up 


This sequence moves the cursor one line towards the top. In contrast 
to ESC A, however, if the cursor is already in the top line, a blank 
line is inserted and the remainder of the screen is scrolled down a line 
correspondingly. The column position of the cursor remains 
unchanged. 


ESC J Clear below cursor 


ESC 


By means of this function, the rest of the screen below the current 
cursor position is cleared. The cursor position itself 1s not changed. 


K Clear remainder of line 

This ESC sequence clears the rest of the line in which the cursor is 
found. The cursor position itself is also cleared, but the position is 
not changed. 


ESC L Insert line 


This makes it possible to insert a blank line at the current vursor 
position. The remainder of the screen is shifted down; the lowest line 
is then lost. The cursor is placed at the start of the new line after the 
insertion. 


ESC M Delete line 


This function clears the line in which the cursor is found and moves 
the rest of the screen up one line. The lowest screen line then 
becomes free. After the deletion, the cursor is moved up to the first 
column of the line that takes the place of the deleted line. 
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ESC Y Position cursor 

This is among the most important functions. It allows the cursor to be 
positioned at any place on the screen. The function needs the cursor 
line and column as parameters, which are expected in this order with 
an offset of 32. If you want to set the cursor to line 7, column 40, 
you must output the sequence ESC Y CHR$(32+7) CHR$(32+40). 
Lines and columns are counter starting at zero; for an 80x25 screen 
the lines are numbered from 0 to 24 and the columns from 0 to 79. 


The remaining ESC sequences of the VT52 terminal start with a lower case 
letter. 


ESC b Select character color 
With this function you can select the character color for further 
output. With a monochrome monitor you have choice between just 
O=white and 1=black. For color display you can select from 4 or 16 
colors depending on the mode. Only the lowest four bits of the 
parameters are evaluated (mod 16). You can use the digit 1" for the 
color 1 as well as the letters "A" or "a" in addition to binary one. 


ESC c Select background color 
This function serves to select the background color in a similar 
manner. If you choose the same color for character and background, 
you will, of course, not be able to see text output any more. 


ESC d Clear screen to cursor position 
This sequence causes the screen to be erased starting at the top and 
going to the current position of the cursor, inclusive. The position of 
the cursor is not changed. 


ESC e Enable cursor 
Through this escape sequence the cursor becomes visible. The cursor 
can, for example, be enabled when waiting for input from the user. 


ESC f Disable cursor 
Turns the cursor off again. 
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ESC j Save cursor position 


If you want to save the current position of the cursor, you can use 
this sequence to do so. Unfortunately, this function is also used by 
other ESC sequences, so the stored value is no longer available to 
you if you use some other sequences. 


k Set cursor to the saved position 

This is the counterpart of the above function. It sets the cursor to the 
position which was previously saved with ESC j. If no cursor 
position was saved, the cursor will go to the home position. 


1 Clear line 

Clears the line in which the cursor is located. The remaining lines 
remain unaffected. After the line is cleared, the cursor is located in the 
first column of the line. 


ESC o Clear from start 


ESC 


ESC 


ESC 


This clears the current cursor line from the start to the cursor position, 
inclusive. The position of the cursor remains unchanged. 


p Reverse on 

The reverse (inverted) output is enabled with this sequence. For all 
further output, the character and background colors are exchanged. A 
monochrome monitor will show white type on a black background. ~ 


q Reverse off 
This sequence serves to re-enable the normal character display mode. 


v Automatic overflow on 
After executing this sequence, an attempted output beyond the end of 
line will automatically start a new line. 


w Automatic overflow off 
This deactivates the above sequence. An attempt to write beyond the 
line will result in all following characters being written in the last 


~ column. 
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Similar functions are available to you under VDI. The VDI escape functions 
(opcode 5) serve this purpose. The appropriate screen function is selected 
by choosing the proper function number. Note, however, that under VDI 
the line and column numbering does not begin with zero but with one. 


Under VDI there 1s also a function which outputs a string at specific screen 
coordinates. If necessary, you can use the ESC functions of the VT52 
emulation in addition. 


The output of "unprintable" control characters 


The three system fonts of the ST have also been supplied with characters for 
the ASCII codes zero to 31, which are normally interpreted as control 
codes. On the ST, only codes 7 (BEL), 8 (BS backspace), 9 (TAB), as well 
aS 10, 11, and 12 (LF linefeed, VT vertical tab, and FF form feed all — 
generate a linefeed) plus 13 (CR carriage return) have effect, in addition to 
ESC. The remaining codes have no effect. How do we access the characters 
below 32? 


To do this, an additional device number 1s provided in the BIOS function 3 
“conout'. Normally number 2 "con" serves for output to the screen. If one 
selects number 5, however, all the codes from, 0 to 255 are outputted as 
printable characters, control codes are no longer taken into account. 


You will find the three ST system fonts pictured in the Appendix. 
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3.7 The ST System Variables 


The ST uses a set of system variables whose significance and addresses will 
not change in future versions of the operating system. If you use other 
variables, such as those from the BIOS listing which are not listed here, you 
should always remember that these could have a different meaning in a new 
version of the operating system. The system variables are in the lower RAM 
area directly above the 68000 exception vectors, at address $400 to 1024. 
The address range from O to $7FF (2047) can be accessed only in the 
Supervisor mode. An access in the user mode leads to a bus error. 


In the following listing we will use the original names from Atari. In 
addition to the address of the given variable, typical contents and the 
significance will be described. Two values are sometimes given for one 
address: The first signifies the address in the ROM version of the operating 
system, while the second address refers to the operating system when in 
RAM, unless stated otherwise in the text. 


Address length name sample contents 
$400 L etv_timer SFCA62A / $104B8 
This is the GEM event timer vector. It handles periodic GEM tasks. 


$404 L etv_critic SFC0744 / $65D2 


Critical error handler. Under GEM this pointer points to 
$FE3226/$294DE. There an attempt is made to correct disk errors, 
such as if a another disk 1s requested in a single-drive system. 


$408 L etv_term SFCO5CO / $644E 
This 1s the GEM vector for ending a program. 
$40C 5L etv_xtra 
Here is space for 5 additional GEM vectors, presently not yet used. 


$420 L memvalid $752019F3 


If the memory location contains the given value, the configuration of 
the memory controller is valid. 
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$424 


$426 


S42A 


$42E 


$432 


$436 


S43A 


$43E 


$440 


W memctrl $05 


This is a copy of the configuration value in the memory controller. 
The value given applies for a 1MB machine. 


L resvalid $31415926 


A given value located here causes a jump to the reset vector ($42A). 


Vf resvector SFC0008 
See above. 
L phystop $80000 / $100000 


This is the physical end of the RAM memory; $80000 for a 512K 
machine and $100000 for a IMB machine. 


L _membot $A100 / $39FFO 

The user memory begins here (TPA, transient program area). 
L _memtop $F8000 

This is the upper end of the user memory. 
L memval2 S237698AA 

This value and "memvalid" declare the memory configuration. 
W flock 0 


If this variable contains a value other than zero, a disk access is in 
progress and the VBL disk routine is disabled. 


WwW seekrate 3 


The seek rate (the time it takes to move the read/write head to the next 
track) is determined according to the following table: 


Seek rate Time 


0 6 ms 
pi 12 ms 
z 2 ms 
3 3 ms 
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ess. 


$442 


$444 


$446 


$448 


3 44C 


S44E 


$452 


$454 


W _timer ms $14, 20 ms 
The time span between two timer calls, 20 ms corresponds to 50 Hz. 
Ww _fverify SFF 


If this memory location contains a value other than zero, a verify is 
performed after every disk write access. 


WwW _bootdev 0 


Contains the device number of the drive from which the operating 
system was loaded. 


W palmode 0 


If this variable contains a value other than zero, the system is in the 
PAL mode (50 Hz); if the value is zero, it means the NTSC mode. 


W defshiftmod 0 


If the Atari is switched from monochrome to color, it gets the new 
resolution from here (O=low, 1 medium resolution). 


WwW sshiftmd $2 


Here 1s a copy of the register contents for the screen resolution. 


0 320x200, low resolution 

1 640x200, medium resolution 
2 640x400, high resolution 
L _v_bas_ad SF8000 


This variable contains a pointer to video RAM (logical screen base). 
The screen address must always begin on a 256 byte boundary. 


W vblsem 1 


If this variable is zero, the vertical blank routine is not executed. 


WwW nvbls 8 


Number of vertical blank routines. 
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$456 


S45A 


S45E 


$462 


$466 


S46A 


S46E 


$472 


$476 


S47A 


L _vblqueue S4CE 


Pointer to a list of nvb1s routines which will be executed during the 
VBL. 


L colorptr 0 


If this value is not zero, it is interpreted as a pointer to a color palette 
which will be loaded at the next VBL. 


L screenpt 0 


This is a pointer to the start of the video RAM, which will be set 
during the next VBL (zero if no new address is to be set). 


L _vbclock S2D26A 
Counter for the number of VBL interrupts. 
L _frclock $2D267 
Number of VBL routines executed (not disabled by vblsem). 
L hdv_init SFCOD60 / S$6BEE 
Vector for hard disk initialization. 
L Swv_vec $FC0020 / $6120 
Vector for monitor change. A branch is made through this vector 
when another monitor (color/monochrome) is connected (default is 
reset). 
L hdv_bpb SFCODE6 / $6C74 
Vector to get the parameter block for a hard disk (BIOS function 7). 
L hdv_xrw $FC10D2 / $6F60 
Read/write routine vector for a hard disk (BIOS function 4). 
L hdv_boot SFC137C / $720A 


Vector for loading a boot sector. 
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S47E L hdv_ mediach $FCOF96 / S6E24 


Media change routine vector for hard disk (BIOS function 9). 


$482 WwW _emdload 0 


If the boot program sets this variable to a value other than zero, the 
ST attempts to load a program called "COMMAND.PRG" once the 
operating system loads (e.g. an application other than the Desktop). 


$484 B conterm 6 


Attribute vector for console output: 


Bit Meaning 
0 Key click on/off 
i Key repeat on/off 
2 Tone after CTRL G on/off 
s "kbshift™ is returned in bits 24-31 for the 


BIOs. function, “conin” 
S48E 4L themd 0 
Memory descriptor, filled out by the BIOS function get mpb. 


S49E 2W md 0 


Space for additional memory descriptors. 
$4A2 L savptr $90C 

Pointer to a save area for the processor registers after a BIOS call. 
S4A6 W _nflops 2 

Number of connected floppy disk drives (0 or 2). 
$4A8 L con_state SFC41BC / SA0O4A 


Vector for screen output; set by ESC functions to the appropriate 
routine, for example. 


S4AC W Save row 0 


Temporary storage for positioning the cursor with ESC Y. 
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$ 4AE 


$4B2 


S4BA 


$ 4BE 


$4C2 


$4C6 


S4CA 


$4CE 


L sav_context 0 


Pointer to a temporary areas for exception handling. 


2L _bufl $60A4, $60CC 


Pointer to two buffer list headers of GEMDOS. The first header is 
responsible for data sectors, the second for the FAT (file allocation 
table) and the directory. Each buffer control block (BCB) is 
constructed as follows: 


long BCB S4F8A, pointer to next BCB 

aie drive -l, drive number or -1l 

int type 2 buffer type 

int rec $41C record number in this buffer 

int dirty 0 — dirty flag (buffer changed) 

long DMD $2854 pointer to drive media descriptor 


long buffer $4292 pointer to the buffer itself 
L _hz 200 $71280 
Counter for 200 Hz system clock 
4B the env 0 
Default environment string, four zero bytes. 
L _drvbits 3 


32-bit vector for connected drives. Bit O stands for drive A, bit 1 for 
drive B, and so on. 


L _dskbufp $167A 


Pointer to a 1024-byte disk buffer. The buffer is used for GSX 
graphic operations and should not be used by interrupt routines. 


L _autopath 0 
Pointer to autoexecute path. 
8L _vbl_list $FD03C4,0,0.. / $16252,0,0.. 


List of the eight standard VBL routines. 
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$ 4EE 


S4F2 


S4F6 


S4FA 


S4FE 


$502 


$506 


SSOA 


W _dumpflg $FFFF 
This flag is incremented by one when the ALT and HELP keys are 
pressed simultaneously. A value of one generates a hardcopy of the 
screen on the printer. A hardcopy can be interrupted by pressing ALT 
HELP again. 

L _sysbase SFC0000 / $6100 
Pointer to start of the operating system. 

L _shell _p 0 
Global shell information. 

i; end os $A100 / $3A4A0 
Pointer to the end of the operating system in RAM, start of the TPA. 


L exec os SFD8E98 / $1F600 


Pointer to the start of the AES. Normally branched to after the 
initialization of the BIOS. 


L dump vec SFCOC2C / S$6ABA 


This vector is jumped to when a hardcopy is being printed (XBIOS 
function 20). 


L prt stat $FC1F34 / $7D2E 
Printer status vector for hardcopy. 

L prt_vec SFC1EAO0 / $7D2E 
Printer output vector for hardcopy. 

L aux stat SFC1IF6E / S$7TDFC 


Vector for getting serial output status during hardcopy. 
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$512 


SS1A 


S51E 


$53E 


S55E 


SS7E 


L aux vec SFC1F86 / $7E14 


Vector for serial output of the hardcopy function. 


I, memval3 S55S55AAAA 


Contains the variable of the “magic number" memval. Keeps the 
memory configuration constant after a reset (together with memvalid 
and memvalid2). 


8L bconstat_vec SFC0670, $FC2138, $FC2226, 
SFC2044, $FC0670, $FC0670, 
$FC0670, $SFC0670 


Eight pointer to routines for getting input status (BIOS function 1, 
bconstat). The first value applies to device number QO, the next for 
device 1, etc., up to device 7. The address $FC0670 points direct to 
an rts command. 


8L bconin vec $FC2104, $FC2150, $FC223C, 
SFC2060,$FC0670, $FC0670, 
SFC0670, $FC0670 


The vector table has an equivalent function to the above. There, 
however, the addresses for BIOS function 2 (bconin) are kept. 


8L bcostat_vec $FC2124, $FC219A, $FC226C, 
SFC21DC, $FC2004, $FC0670, 
SFC0670, $FC0670 


These addresses contain the output status for device numbers 0 to 7. 
They are jumped to from BIOS function 8, bcostat. 


8L bconout vec $FC2090, $FC21B4, $FC434C, 
$FC2016, S$FC21EE, $FC4340, 
SFC0670, $FC0670 


These addresses are the ones for character output. These correspond 
to the BIOS function 3, bconout. 
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3.8 The 68000 Instruction Set 


If you are already familiar with the machine language of some 8-bit 
processor, forget everything you know. If you do, it will make it easier to 
understand the following material! 


The 68000 processor is fundamentally different in construction and 
architecture from previous processors (including the 8086!). The essential 
difference does not lie in the fact that the standard processing width is 16 
and not 8 bits (which is sometimes a drawback and can lead to 
programming errors), but in the fact that, with certain exceptions, the 
internal registers are not assigned to a specific purpose, but can be viewed 
as general-purpose registers, with which almost anything 1s possible. 


In earlier processors, the accumulator was always the destination for 
arithmetic operations, but it is completely absent in the 68000. There are 
eight data registers (DO-D7) with a width of 32 bits, and as a general rule, at 
least one of these is involved in an operation. There are also eight address 
registers (AO-A7), each with 32 bits, which are usually used for generating 
complex addresses. Register A7 has a set assignment--it serves as the stack 
pointer. It is also present twice, once as the user stack pointer (USP) and 
once as the supervisor stack pointer (SSP). The distinction is made because 
there are also two operating modes, namely the user mode and the 
supervisor mode. 


These two are not only different in that they use different stack pointers, but 
in that certain instructions are not legal in the user mode. These are the 
so-called privileged instructions (see also instruction description), with 
whose help an unwary programmer can easily "crash" the system rather 
spectacularly. This is why these instructions create an exception in the user 
mode. An exception, by the way, is the only way to get from the user mode 
to the supervisor mode. | 


In addition there 1s the status register, the upper half of which is designated 
as the system byte because it contains such things as the interrupt mask, 
things which do not concern the "normal" user, making access to this byte 
also one of the privileged instructions. The lower byte, the user byte, 
contains the flags which are set or cleared based on the result of operations, 
such as the carry flag, zero flag, etc. As a general rule, the programmer 
works with these flags indirectly, such as when the execution of a branch is 
made conditional on the state of a flag. 


258 


Abacus Software Atari ST Internals 


Two things should be mentioned yet: Multi-byte values (addresses or 
operands) are not stored in memory as they are with 8-bit processors, in the 
order low byte/high byte, but the other way around. Four-byte expressions 
(long word) are stored in memory (and the registers of course) with the 
highest-order byte first. 


The second is that unsupported opcodes do not lead to a crash, but cause a 
special exception, whose standard handling must naturally be performed by 
the operating system. 


3.8.1 Addressing modes 


This is probably the most interesting theme of the 68000 because the 
enormous capability first takes effect through the many various addressing 
modes. 


The effective address (the address which, sometimes composed of several 
components, finally determines the operand) is fundamentally 32 bits wide, 
even if one or more the components specified in the instruction is shorter. 
These are always sign-extended to the full 32-bit width. 


The charm of the addressing lies in the fact that almost all instructions 
(naturally with exceptions), both the source and destination operands, can 
be specified with one of the addressing modes. This means that even 
memory operations do not necessarily have to use one of the registers; 
memory-to-memory operations are possible. 


In the assembler syntax, the source operand 1s given first, followed by the 
destination operand (behind the comma). 
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Register Direct 


The operand is located in a register. There are two kinds of register direct . 
addressing: data register direct and address register direct. 


In the first case, the operand may be bit, byte, word, or long word-oriented; 
in the second case a word or long word is required, in case the address 
register is the destination of the operation. 


Example: ADD.B DO,D1 or ADDA.W DO,A2 


Absolute Data Addressing 


The operand is located in the address space of memory. This can also be a 
peripheral component, naturally (see MOVEP). The address is specified in 
absolute form. 


This can have a width of a long word, whereby the entire address space can 
be accessed, or it can be only one word wide. In this case 1s sign-extended 
(the sign being the highest-order bit) to 32 bits. For example, the word 
$7FFF becomes the long word $00007FFF, while $FFFF becomes 
$FFFFFFFF. Only the lower 32K and the upper 32K of the address space 
can be accessed with the short form. This addressing mode is often used in 
the operating system of the ST because important system variables are 
stored low in memory and all peripheral components are decoded at the top. 


Example: MOVE.L S7FFF,$01234567 


Instructions in which both operands are addressed with a long word are the 
longest instructions 1n the set, consisting of 10 bytes. 
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Program Counter Relative Addressing 

This addressing mode allows even constants to be addressed in a completely 
relocatable program, since the base of the address calculation 1s the current 
state of the program counter. 

The are two variations. In the first, a 16-bit signed offset is added to the 
program counter, and in the second, the contents of a register 
(sign-extended if only one word is specified) are also added in, though here 
the offset may be only 8 bits long. 


Example: MOVE.B $1234 (PC) ,$12(PC,DO.W) 


Register Indirect Addressing 

There are several variations of this, and they will be discussed individually. 
Register Indirect 

Here the operand address is located in an address register. 

Example: CLR.L (AO) 

Postincrement Register Indirect 


The operand is addressed as above, but the contents of the address register 
are incremented by the operand length, by 1 for xxx.B or 4 for xxx.L. 


Example: MOVE.B #0, (A0+), (Al)+ or CMP.L #23, (Al) + 
Predecrement Register Indirect 


Here the address register is decrement by the length of the operand before 
the addressing. 


Example: CMPI.W $0123,-(A3) 

Register Indirect with Offset 

A 16 bit offset will be added to the contents of the address register. 
Example: EOR.L DO,$1234 (A4) 
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Indexed Register Indirect with Offset 

As above, but the contents of another register (address or data) are also 
added in, taking the sign into account. The offset may have a width of 8 bits 
here, however. 


Example: MOVE.W $12 (A5,A6.L),D1 


Immediate Addressing 


Here the operand is contained as such in the instruction itself. Naturally, an 
operand specified in this manner can serve only as a source. The immediate 
operands can, as a general rule, be any of the allowed widths. 


Example: ADDI.W #$1234,D5 

In the variant QUICK, the constant may be only 3 bits long, therefore 
having a value from 0-7. An exception is the MOVE command, where the 
constant may have 8 bits, but in which only a data register is allowed as the 
destination. 


Example: ADDQ.L #1,A0 or MOVEQ #123,D1 


Implied Register 


This addressing mode is mentioned only for the sake of completeness and in 
it, an operand address is already determined by the instruction itself. The 
operands are either in the program counter, in the status register, or the 
system stack pointer. 


Example: MOVE SR,D6 
Regarding the offsets, it should be noted that they are signed numbers in 


two's complement. Their highest-order bit forms the sign. With an 8-bit 
value, an offset of +127/-128 is possible, and about +32K with 16 bits. 


262 


Abacus Software Atari ST Internals 


3.8.2 The instructions 


In the following instruction description, the individual bit patterns are not 
listed since this would lead us too far in this connection. Additional 
information can be gathered from books like the M68000 16/32-Bit 
Microprocessor Programmer's Reference Manual (Motorola). 


The instructions are also explained only in their base form and variations are 
mentioned only in name. We will briefly explain what the individual 
variations can look like here. 


The variations are indicated by letter after the operand. This can be one of 
the following: 


A indicates that the destination of the operation is an address register. 
Word operations are sign-extended to 32 bits. 


I indicates an immediate operand as the source of the operation. I 
operands may assume all widths as a general width. 


Q means quick and represents a special form of immediate addressing. 
Such an operand is usually three bits wide, corresponding to a value 
range of O to 7. This limited range has the advantage that the opérand 
will fit into the opcode. Since there is no special command for 
incrementing a register, something like ADDQ.L #1,A0 works well in 
its place. An exception is MOVEQ. Here the operand may have a value 
of 0-255. 


X indicates arithmetic operations which use the X flag. This flag has a 
special significance. It 1s set equal to the carry flag for all arithmetic 
operations. The carry flag, however, is also affected by transfer 
operations while the X flag is not so that it remains available for further 
calculations. This is especially useful for computations with higher 
precision than the standard 32 bits, where temporary results must first 
be saved, and where the carry flag can be changed as a result. 


All instructions have a suffix after the opcode of the form .B, .W, or .L. 
This suffix indicates the processing width of the operation. Although a data 
register, for example, has a width of 32 bits = 4 bytes = 1 long word, the 
instruction CLR.B D0 clears only the lowest-order byte of the register. For 
registers, .W specifies the lower word. The higher-order word is not 
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explicitly addressable. If the operand is in memory, it is important to know 
that .W and .L operands must begin on an even address. The same applies 
for the opcode as such, which also always comprises one word. 


If the destination of an operation is an address register, only operands of 
type .W and .L are allowed, whereby the first 1s sign-extended to a long 
word. : 


Some listings contain instructions of the form MOVE.L #27,D0. The 
programmer then assumes that the assembler will produce #$0000001B 
from #27. 


Now to the individual instructions: 


ABCD Add Decimal with Extend 
There is one data format which we have not yet discussed: the BCD 
format. This means nothing more than "Binary-Coded Decimal" and it 
uses digits in the range 0-9. Since this information requires only 4 bits, 
a byte can store a two-digit decimal number. The instruction ABCD can 
then add two such numbers. The processing width 1s always 8 bits. 


ADD Add Binary 
This instruction simply adds two operands. 
Variations are ADDA, ADDQ, ADDI, and ADDX. 


AND Logical AND 
Two operand are logically combined with each other according the 
AND function. 
Variation: ANDI 


ASL Arithmetic Shift Left 

The operand is shifted to the left byte by the number of positions given, 
whereby the highest-order bit is copied into the C and X flags. A 0 1s 
shifted in at the right. If a data register is shifted, the processing width 
can be any. The number of places to be shifted is either specified as an I 
operand (3 bits) or is placed in an additional register. If a memory 
location is shifted, the processing width is always one word. A counter 
is then not given; it 1s always =1. 


ASR Arithmetic Shift Right 
The operand is shifted to the nght, whereby the lowest bit 1s copied to 
C and X. The sign bit is shifted over from the left. See ASL for 
information about processing width and counter. 
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Bec Branch Conditionally 
The branch destination is always a relative address which is either one 
byte or one word long (signed!). Correspondingly, the branch can 
jump over a range of +127/-128 bytes or +32K-1/-32K. The point of 
reference 1s the address of the following instruction. 


Atari ST Internals 


Whether or not this instruction is actually executed depends on the 
required condition, which is verified by means of the flags. Here are the 
variations and their conditions. A minus sign before a flag indicates that 
it must be cleared to satisfy the condition. Logical operations are 


indicated with ''*" for AND and "/" for OR. 


BRA Branch Always 

BCC Branch Carry Clear 

BCS Branch Carry Set 

BEQ Branch Equal 

BGE Branch Greater or Equal 

BGT Branch Greater Than 

BHI Branch Higher 

BLE Branch Less or Equal 

BLS Branch Lower or Same 

BLT Branch Less Than 

BMI Branch Minus 

BNE Branch Not Equal 

BPL Branch Plus 

BVC Branch Overflow Clear 

BVS Branch Overflow Set 
BCHG Bit Test and Change 


no condition 

= 

ie 

Z, 

N*V/-N*-V 
N*V*-Z/-N*-V*-Z 
—C*—-Z 
Z/N*-V/-N*V 
C/2Z 

N*-V/-N*V 


The specified bit of the operand will be inverted. The original state can 
be determined from the Z flag. The operand is located either in memory 
(width=.B) or in a data register (width=.L). The bit number is given 
either as an I operand or is located in a data register. 


BCLR Bit Test and Clear 
The specified bit is cleared. Everything else is handled as per BCHG. 


BSET Bit Test and Set 
The specified bit is set. Boundary conditions are per BCHG. 


BSR Branch to Subroutine 
This 1S an unconditional branch to a subroutine. Branch distances as for 


Bec. 
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BIST Bit Test 
The bit is only tested as to its condition. Everything else as per BCHG. 


CHK Check Register Against Boundaries 
A data register is checked to see if its contents are less than zero or 
greater than the operand. Should this be the case, the processor 
executes an exception. The program is continued at the address in 
memory location $18 (vector 6). Otherwise no action is taken. The 
processing width is only word. 


CLR Clear Operand 
The specified operand is cleared (set to zero). 


CMP Compare 
The first operand is subtracted from the second without changing either 
of the two operands. Only the flags are set, according to the result. 
Variations: CMPA and CMPI 
Both operands are addresses with the addressing mode (Ax)+ with the 
variant CMPM. 


DBcc Test Condition, Decrement and Branch 
A data register (word) is decremented and the flags are checked for the 
specified condition. A branch is performed if the condition is not 
fulfilled and the register is not -1. Branch conditions and ranges as per 
Bec. 


DIVS Divide Signed 
The second operand 1s divided by the first operand, taking the sign into 
account. Afterwards the second operand contains the integer quotient in 
the lower word and the remainder in the upper word, which has the 
Same sign as the quotient. The data width of the first operand 1s set at 
.W and at .L for the second. 


DIVU Divide Unsigned 
Operation as above, but the sign is ignored. 


EOR Exclusive OR 
The two operands are logically combined according to the rules of 
EXOR. 
Variations: EORI 


EXG Exchange Registers 
The two registers specified are exchanged with each other. 
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EXT Sign Extend 
The operand is filled to the given processing width with its bit 7 (in the 
case of .B) or bit 15 (.W). 


JMP Jump 
Unconditional jump to the specified address. The difference between 
this and BRA is that here the address is not relative but absolute, that is, 
the actual jump destination. 


JSR Jump to Subroutine 
Jump to a subroutine. The difference from BSR 1s as above. 


LEA Load Effective Address 
This often-misunderstood instruction loads an address register not with 
the contents of the specified operand address as is normal for the other 
instructions, but with the address as such! 


LINK Link Stack 
This instruction first places the given address register on the stack. The 
contents of the stack pointer (A7) are then placed in this register and the 
offset specified 1s added to the stack pointer. 


With this practical instruction, data areas can be reserved for a 
subroutine, without having to make room in the program itself, which 
would also be impossible in programs which run in ROM. The 
C-compiler makes extensive use of this capability for local variables. 


LSL Logical Shift Left 
Function and limitations as per ASL. 


LSR Logical Shift Right 
Function and limitations as per ASR, except here the sign is not shifted 
in on the left, but a 0. 


MOVE 
The first operand is transferred to the second. 
Variations: MOVEA, MOVEQ 


MOVEM Move Mulitple Registers 
Here an operand can consist of a list of registers. This can be used to 
place all of the registers on the stack, for instance. 
Example: MOVEM.L AO-A6/D0-D7,-(A7) 
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MOVEP Move Peripheral Data 

This specialty 1s made expressly for the operation of peripheral 
components. As a general rule, these work only with an 8-bit data bus, 
and are then connected only to the upper or lower 8 bits of the 68000's 
data bus. If a word or long word is to be transferred, the bytes must be 
passed over either the upper or lower byte of the data bus, depending 
on whether the address is even or odd. The address is then always 
incremented by two so that the transfer always continues on the same 
half of the data bus on which it was begun. Corresponding to the 
purpose of this instruction, one operand is always a data register, and 
the other is always of type register indirect with offset. 


MULS Multiply Signed 
Signed multiplication of two operands. 


MULU Multiply Unsigned 
Multiplication of two operands, ignoring the sign. 


NBCD Negate Decimal with Extend 
A BCD operand is subjected to the operation 0-operand X. 


NEG Negate Binary 
The operand is subjected to the treatment 0-operand. 
Variations: NEGX 


NOP No Operation 
As the name says, this instruction doesn't do anything. 


NOT One's Complement 
The operand 1s inverted. 


OR Logical OR 
The two operands are combined according to the rule for logical OR. 


PEA Push Effective Address 
The address itself, not its contents, is placed on the stack. 


RESET Reset External Devices 
The reset line on the 68000 is bidirectional. Not only can the processor 
be externally reset, but it can also use this instruction to reset all of the 
peripheral devices connected to the reset line. 
This is a privileged instruction! 
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ROL Rotate Left 
The operand is shifted to the left, whereby the bit shifted out on the left 
will be shifted back in on the right and the carry flag is affected. 
Processing widths and shift counter as per ASL. 


ROR Rotate Right 
As above, but shift from left to nght. 


ROXL Rotate Left with Extend 
As ROL, but the shifted bit 1s first placed in the X flag, the previous 
value of which is shifted in on the right. 


ROXR Rotate Right with Extend 
As above, but reversed shift direction. 


RTE Return from Exception 
Return from an exception routine to the location at which the exception 
occurred. 


RTS Return from Subroutine 
Return from a subroutine to the location at which it was called. 


RTR Return and Restore 
As above, but the CC register (the one with the flags) 1s first fetched 
from the stack (on which it must have first been placed, because 
otherwise execution will not return to the proper address. 


SBCD Subtract Decimal with Extend 
The first operand is subtracted from the second. Refer to ABCD for 
information on the data format. 


Scc Set Conditionally 
The operand (only .B) is set to $FF if the condition is fulfilled. 
Otherwise it is cleared. Refer to Bcc for the possible condition codes. 


STOP 
The processor is stopped and can only be called back to life through an 
external interrupt. 
This is a privileged instruction! 


SUB Subtract Binary 
The first operand is subtracted from the second. 
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SWAP Swap Register Halves 
The two halves of a data register are exchanged with each other. 


TAS Test and Set Operand 
The operand (only .B) is checked for sign and 0 (affecting the C and N 
flags). Bit 7 1s then set to 1. 


TRAP 
The applications programmer uses this instruction when he wants to call 
functions of the operating systems. This instruction generates an 
exception, which consists of continuing the program at the address 
determined by the given vector number. See the chapter on the BIOS 
and XBIOS for the use of this instruction. 


TRAPYV Trap on Overflow 
If the V flag is set, an exception is generated by this instruction, 
resulting in program execution continuing at the address in vector 7 


($1C). 


TST Test 
Action like TAS, but the operand is not changed. 


UNLK Unlink 
This instruction is the counterpart of LINK. The stack pointer (A7) 1s 
loaded with the given address register and this is supplied with the last 
stack entry. In this manner the area reserved with LINK 1s released. 


Addendum to the condition codes: The conditions listed under Bcc are not 
complete, because the additional conditions do not make sense at that point. 
But the instructions DBcc and Scc have the additional variations T (DBT, 
ST) and F (DBF, SF). T stands for true and means that the condition 1s 
always fulfilled. F stands for false and is the opposite: the condition is never 
fulfilled. 


DBF can also use the syntax DBRA. 
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3.9 The BIOS Listing 


The situation concerning ST software has changed radically since the Spring 
of 1985. Nowadays you can find a wealth of programs which are fully 
supported by GEM, and as a consequence are easy to operate. In addition, 
many dealers have gone over exclusively to the ST. 


One thing is certain: If available software and hardware under development 
are any indicators, the Atari ST has caught on as an incredibly popular 
computer. 


The following is the commented BIOS listing of the Atari ST. It 1s patterned 
after the ROM version of February 1986. The listing includes system 
initialization, the complete BIOS and XBIOS, as well as the VTS2 screen 
driver. We don't expect any changes to this listing in the near future. Any 
alterations to the ST that affect this listing will be reflected in later editions 
of this book (we plan on keeping abreast of any changes, naturally). 


The variables in the ROM version lie in the same range (up to $6100) as the 
diskette version of TOS from February 1986. 


If you want to use system routines from TOS in your own programs you 
should only use the call through the corresponding TRAP. Otherwise, your 
program won't run with any altered versions of TOS. This applies at the 
Same time to the use of variables which are not contained in the list of 
system variables. 


Otherwise, you can call the BIOS routines as excellent illustrations in 68000 
assembly language. If your own routines are to be complex and transparent, 
you can convert most of them to C compiled code. Then you can recognize 
most of these routines since they start with link #n,A6. A6 as a base 
register will communicate with given parameters if there is a positive offset; 
a negative offset will communicate with the local variables of this routine. 
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4.1 The System Fonts 


The operating system contains three different fonts for character output. 


The 6x6 font is used by the icons, the 8x8 font is used as the standard 
output on a color monitor, and the 8x16 font is used for the monochrome 
monitor output. The chart on the next page includes the characters with the 
ASCII codes 1 to 255. 
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8X8 System Font 8X16 System Font 


6X6 System Font 
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4.2 Alphabetical listing of GEMDOS functions 


Name Opcode (hex) Page Number 
Cauxin 03 108 
Cauxis 12 115 
Cauxos 13 115 
Cauxout 04 109 
Cconin Ol 107 
Cconis OB 113 
Cconos 10 114 
Cconout Q2 108 
Cconrs OA 112 
Cconws O9 111 
Cnecin O08 111 
Cprnos 11 115 
Cprnout O5 109 
Crawcin Q7 110 
Crawio 06 110 
Decreate 39 123 
Ddelete 3A 124 
Dfree 36 122 
Dgetdrv 19 116 
Dgetpath 47 135 
Dsetdrv OE 114 
Dsetpath 3B 125 
Fattrib 43 132 
Fclose 3E 128 
Fcreate ‘i é 126 
Fdatime 57 143 
Fdelete 41 130 
Fdup 45 134 
Fforce 46 134 
Fegetdta 2F 120 
Fopen 3D 127 
Fread 3F 129 
Frename 56 143 
Fseek 42 131 
Fsetdta 1A 116 
Fsfirst 4E 140 
Fsnext 4F 142 
Fwrite 40 130 
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ae a 


Malloc 48 135 
Mfree 49 137 
Mshrink 4A 137 
Pexec 4B 138 
Pterm 4C 140 
Pterm0 OO 107 
Ptermres 31 121 
Super 20 Lay 
Sversion 30 121 
T getdate 2A 118 
Tgettime 2 119 
Tsetdate 2B 119 
Tsettime 2D 120 
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4.3 The blitter chip 


Anyone who has followed the development of the ST has surely heard the 
word blitter. More than two years were spent developing the blitter chip. 
The main advantage of this chip is its speed, working with data in the DMA 
register. The blitter uses a memory range independent of the 68000 
microprocessor. Without the blitter chip, you need several kilobytes of 
program code to realize graphics through software. 


The basic graphic routines of the ST are accessed by software through 
line-A opcodes. The blitter can take on parts of these routines and execute 
them faster than the 68000 could handle them. That is first taken by the 
BITBLT function, shifting the established pixel-oriented memory range. 
However, the fill can be taken up in any memory range. The details of the 
blitter options follow later. First let's look at chip design. 


Figure 4.3-1 BLITTER 
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Since the blitter is a DMA device, it must be able to transfer the processor in 
an idle state. The processor needs the 68000 pins BR (Bus Request), BG 
(Bus Grant) and BGACK (Bus Grant Acknowledge). The BG pin conveys 
everything needed for the address and data bus. If the processor recognizes 
a Bus Request, BG tells the attached device that there is now a bus available 
for the DMA device. Now a short delay loop executes until the 68000 stops 
its activity in the different pins (see Section 1.2). As long as the DMA entry 
has established that the processor is no longer active, then it restarts with 
the help of BGACK. After data transfer finishes, BGACK clears, and the 
processor receives control of the bus. 


The blitter chip can use the entire address range of the 68000 (16 
megabytes). In order to manipulate the data in memory through 
programming, the processor cannot produce any control signals. These 
controlled by the READ/WRITE pin, which determines which data is read 
and which is written to memory. Other important signals for accessing 
memory are AS (Address Strobe), LDS (Lower Data Strobe) and UDS 
(Upper Data Strobe). 


The DTACK signal (Data Transfer Acknowledge) invokes the blitter chip 
only, when the processor displays the transfer of data. It cannot do the 
DMA transfer itself, since the RAM chip timing is set by the blitter or the 
CLK signal. Like the other onboard DMA channels (floppy disk and DMA 
port) and the ACIAs, the blitter is also capable of performing interrupts. 
This means that it can create its own interrupts to end data transfers. 
Therefore, it uses the free bit 3 of the MFP interrupt entry (GPIP). This 
option is not usually used by the ST operatng system. However, other 
interrupt-oriented operating systems like RTOS, OS9 or UNIX should have 
blitter integration. 


The last group of blitter connections belong to the power connections. In 


addition to the usual 5 volt current and ground, the blitter needs a time 
signal of 8 mHz. 
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4.3.1 The blitter registers 


The ST blitter chip is the hardware implementation of the BITBLT algorithm 
used in the line-A opcodes. 


Figure 4.3.1-1 shows a block diagram of the blitter functions. The blitter 
can basically set up a source range which can be combined with a current 
raster, a destination range of 16 different logical operands, and a destination 
range in which it stores the result. Both source and destination ranges can 
be stored in the same area of RAM. Unlike the processor, which can only 
operate in bytes and words, the blitter is bit-oriented. This makes the blitter 
ideal for handling bitmapped graphics. It is also practical for normal copy 
and transfer commands, e.g., high-speed RAM disk operations without 
hard disk interrupts. 


The following is a look at the individual registers used by the blitter: 


Figure 4.3.1-1 BLITTER BLOCK DIAGRAM 


Source Source Destination 


Half-tone HOP Logic OP 


New destination data 


The first 16 registers are marked as half-tone RAM, and contain the raster 
used in half-tone operations. The registers are each 16 bits wide. When the 
raster is used, a proportional register for a lin 1s used. The raster repeats 
over all 16 lines. The Line Number register (see below) determines which 
half-tone register is used next. 
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Bit FEDCBA9YI8%7654321 0 
SFF8A00 R/W X X X X X X X X X X X X X X K XHalf-tone RAM 0 
SFF8A02 R/W X X X X X X X X X X X X X KX X XHalf-tone RAM 1 
SFF8A04 R/W X X X X X X X X X X X X KX KX X KHalf-tone RAM 2 
SFF8A06 R/W X X X X X X X X X X X X X X KX KXHalf-tone RAM 3 
SFF8A08 R/W X X X X X X X X X X X X X X KX XHalf-tone RAM 4 
SFF8A0A R/W X X X X X X X X X X X X X X KX KHalf-tone RAM 5 
SFF8A0C R/W X X X X X X X X K X X X X X KX XHalf-tone RAM 6 
SFF8A0E R/W X X X X X X XK X XK X X X X KX X KHalf-tone RAM 7 
SFE8A10 R/W X X X X X X X X X X X X KX X X KXHalf-tone RAM 8 
SFF8A12 R/W X X X X X X X X X X X KX X X KX XHalf-tone RAM 9 
SFF8A14 R/W X X X X X X X X X X X X KX X KX XHalf-tone RAM 10 
SFF8A16 R/W X X X X X X X X X X X X X X KX XHalf-tone RAM 11 
SFF8A18 R/W X X X X X X X X X X X X X X KX XHalf-tone RAM 12 
SFF8A1A R/W X X X X X X X X X X X X KX X X XHalf-tone RAM 13 
SFF8A1C R/W X X X X X X X X X X X X KX KX X XHalf-tone RAM 14 
SFF8A1E R/W X X X X X X X X X X X XK X X X OK Half-tone RAM 15 


The next register 1s called X Increment. This is a leading character 
dependent 15-bit register. The lowest bit is ignored and constantly registers 
OQ. This makes only even numbers possible. The register gives the offset in 
bytes in the next source word in the same line. Normally, the Atari gives a 2 
for monochrome mode. This is also the case when all planes are copied in 
color mode. If a plane is copied in medium-res or low-res mode,then 4 or 8 
must exist 1n this register. 


Bit 


te A 
SFF8A20 R/W X X Source X 
Increment 


(always zero, even increments only) 


Foe DCB 9 8/36. 8 Seek. 0 
XX XXXXXXXXXXX X X 0 
| 


The Source Y Increment register determines how many bytes must be added 
to the current source address, in order to figure out the distance from the 
end of the current line to the start of the next line.In monochrome mode, a 
set of pixels measures 80 bytes: When only a segment of 20 bytes is copied, 
the Source Y Increment gives a value of 60. 


Bit F 
SFF8A22 R/W X Source Y 
Increment 


even increments only) 


a4 32.10 
max xX XX 0 
| 


(always zero, 
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The Source Address register determines the starting address at the beginning 
of the copy. It can read or write long word accesses. Bits 0 and 24-31 are 
used only for even 24- bit addresses. The contents of this register are 
incremented as part of the operation with the help of the above mentioned 
increment register (or decremented, depending on the leading character of 
the increment register). By reading the source address register, the address 
of the source word used next is received. 


Bit fb Bop-CB- A. 9 8276 5-4 Sek Oo 
SFF8A24 R/W - - ------ X X X X X X X 0 Source Address 
High Word 
(unused) (24-bit addresses only) 


Bit- FED C BA 9 8 7 6'5.4-3 2°10 
SFF8A26 R/W X X X X X X X X X X X X X X X DO Source Address 
| Low word 
(always zero, even increments only) 


The next three registers contain the endmask, which states which bits are 
changed and which are unchanged. Since the blitter 1s pixel oriented, but the 
bus accesses RAM in words, the first and the last word are read as bits. To 
write 16 bits over the processor bus, the destination word must first read 
then change the allowable bits, and transfer the result (Read-Modify-Write). 
Endmask 1 does this for the beginning of a line, endmask 3 applies to the 
end of a line. Endmask 2 is used by all other words. It is normally set to 
$FFFF (all bits are altered by it). Thus, a previous reading of the destination 
word is unnecessary. 


Bit FEDCBA9I876543210 
SFF8A28 R/W X X X X X X X X X X X X X X X X-~ Endmask 1 
SFF8A2A R/W X X X X X X X X X X X X X X X X~ Endmask 2 
SFF8A2C R/W X X X X X X X X X X X X X X X X_~ Endmask 3 


The next three registers are Destination X Increment, Destination Y 
Increment and Destination Address. They have the same uses as the above- 
mentioned source registers, except that these three apply to the destination. 


Bit 


Pe D- CB Ao 6.7.6 3S. 4.3 2. 2. 6 
SFF8A2E R/W X X X X X X X X X X K KX X X X NO Destination X 
| Increment 
(always zero, even increments only) 
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Bit FEDCBA9I87654321 0 
SFF8A30 R/W X X X X X X X X X X X X X X X DO Destination Y 
| Increment 
(always zero, even increments only) 
Bit -F & D.C B-A 9 8.7 76:53 .4::3.2 5-0 
SFF8A32 R/W - ------- X X X X X X X X Destination 
Address High Word 
(unused) (24-bit addresses only) 
Bit -FEDCBA9°8.7-6.5.4 3:2.1.0 
SFF8A34 R/W X X X X X X X X X X X X X OX OX OO Destination 


| Address Low Word 
(always zero, even increments only) 


The X Count register informs you how many words are in a destination 
line. The minimum value is 1; the highest is 65536 ($0000). Reading the 
register gives the number of values in this line as words are transferred. 
When the X Count register is loaded with 1, the values in Destination X 
Increment, as well as Source X Increment, are unused. Since the line after a 
word is already the end, and the corresponding Y Increment is used direct. 


The Y Count register determines the number of lines. The smallest value is 
again one, and values of zero are interpreted as 65536. Reading this register 
gives you the number of lines which need copying. After every transferred 
line, the value decrements by one until it reaches 0, ending the transfer. 


Bit FEDCBAS-8.7 65 43 2 1.0 
SFF8A36 R/W X X X X X X X X X X X X X X KX K K-Count 
SFF8A38 R/W X X X X X X X X X X KX XK XK XK K XK Y-Count 


All the abovementioned registers can only be read as words or long words; 
byte access 1s not allowed. 


The HOP register determines the combination of source and half-tone RAM. 
The two lowest bits have the following meanings: 


HOP Combination 

0 All 1-bits 

1 Half-tone RAM 

Pe Source 

3 Source and half-tone RAM 
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You can therefore determine whether the source can be used unaltered (HOP 
= 2), whether the half-tone RAM is combined with the logical AND (HOP = 
3) or whether only the half-tone RAM is used (HOP =1). This is useful, for 
example, when filling an area with a raster pattern. Furthermore, it is still 
possible to fill the destination with 1-bits (HOP = 0). When half-tone RAM 
is used, another register determines which half-tone registers are used. 


Bit IO) D4 a e-1g 
SFF8A3A R/W ------ X X HOP 


Half-tone operation 


The next register determines the receiver of the new destination value, after 
logical operations between destination and source. Here are 16 different 
options in the following table. 


(~s&~d) | (~s&d) | (S&~d) | (s&d) Operation New destination 


all O bits 

source AND destination 

source AND NOT destination 
source 

NOT source AND destination 
destination 

source XOR destination 

source OR destination 

NOT source AND NOT destination 
NOT source XOR destination 

NOT destination 

source OR NOT destination 

NOT source 

NOT source OR destination 

NOT source OR NOT destination 
all 1 bits 


WOW HA UP WNF- OO 


0 
0 
0 
0 
0 
0 
0 
0 
1 
1 
1 
1 
1 
i 
1 
1 


Pe rHOODOOOrFFKFrPFrOCOO 
PEOOrRPKFOOHFOOFRHFOO 
FPoOorFPORPOrFOrFOFOFHOFO 


The most important operations are the following three (Replace mode, 
Source replaces and destination), 6 (XOR mode; overlapping of destination 
and source) and and 7 (OR mode). 


ey ee Oe 2 
SFF8A3B R/W as eg Sal? ee ae OP 
Logical operation 
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Bit T2635 423° 25.0 
SFF8A3C R/W XX X —- X K XK X 
Poti Line number 
pe 2 tl eS eee 
Pe Oe gig SOG 
| HOG 
| Busy 


The next register combines several functions. The lowest 4 bits determine 
which of the 16 half-tone RAM registers are even used. The value is 
incremented or decremented after a line, depending on the leading character 
in the Destination Y Register. When the SMUDGE bit is set, the number of 
the half-tone RAM register is determined by the four lowest bits of the 
above mentioned source data. The selected half-tone operation (HOP) stays 
active. This allows special effects. 


The next bit in this register determines the method of bus access in the 
blitter. When the HOG bit clears, the blitter and processor share the same 
bus. After 64 bus cycles, the blitter stops and the processor takes over the 
bus for 64 bus cycles. When the HOG bit is set, the processor stops until 
the blitter finishes its operations. In either case, other DMA devices (floppy 
and harddisk) have priority over the blitter. The Prefetch mechanism of the 
68000 processor lets you bypass HOG mode, so after the start of the blitter 
the next processor command executes when the blitter is ready. 


The BUSY bit is set, initializing all other blitter registers, in order to start 
the blitter. It waits until the blitter ends its operation. Since the interrupt 
output mirrors the status of the blitter, blitter operations can be ended by an 
interrupt taken from the third bit of the GPIP within the MFP 68901. 


Bit | 65: 4-°3.-2 32° 
SFF8A3D R/W X X-- XX XX 
et ee ae SKEW 
on Unused 
| NFSR 
See ees eee ee 


The last blitter register also has several functions. The lowest four bits 
determine the source operand shifts, to protect the destination operations. 
Since the blitter is bit-oriented, but bus access is word-oriented, the source 
data must move to set the bit positions of half-tone masks and destination 
data. Therefore, two source data words are read, shifting the relevant bits 
for calling in a 16-bit source register (see Figure 4.3.1-1). 
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FXSR and NESR are abbreviations for Force eXtra Source Read and No 
Final Source Read. When the FXSR bit is set, the beginning of each line is 
read as an additional source word. The NFSR bit is set when the last word 
of the source line cannot be read. The use of these bits require changes to 
Source Y Increment and Source Address Register. 


Normally you can access the blitter directly through the operating system. 
When you use the line-A or VDI functions, the operating system can tell 
whether the function is produced by software or by the blitter (see XBIOS 
function $64). 
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4.4 The Mega ST realtime clock 


When the ST was initially released, GEMDOS set the software-run clock in 
two-second increments. In addition, the clock and date needed resetting 
every time the user switched on the computer. 


To get around this, the ROM circuits, keyboard processor and clock IC 
offered some solutions. The Mega ST's clock IC is a permanent solution to 
the problem. Its timekeeping registers are as follows: 


Bit i Ee es as (bits 4-7 unused) 
SFFEFC21 R/W - - -- XX X X one second 
SFFFC23 R/W - ---XX XX ten seconds 
SFFFC25 R/W - - - —- X X X X one minute 
SFFFC27 R/W - - - —- X X X X ten minutes 
SFFFC29 R/W - --- xX X X X one hour 
SFFFC2B R/W - --- X X X X ten hours 
SFFFC2D R/W - -- -X X XK X weekday 
SFFFC2F R/W - - - —- X X X X one day 
SFFFC31 R/W - --- X X X X tenth day 
SFFFC33 R/W - - - —- X X X X one month 
SFFFC35 R/W - - - —- X X X X tenth month 
SFFFC35 R/W - ---X X X X one year 
SFFFC37 R/W - - - — X X X X tenth year 
SFFFC39 R/W - -- - X X X X control register 
SFFFC3B R/W - --- X X XX control register 
SFFFC3D R/W - - - —- X X X X control register 


The RP 5 C 15 appears to be the same as most clock ICs. It has a 
four-bit-wide data and address bus,which addreses a total of 16 registers. 
All of these registers had data width of 4 bits, and contain areas of date and 
time in BCD format. The next three registers ($FFFC3B to $FFFC3F) are 
unknown. They describe some registers of setting the clock, but 
disassembly doesn't give any further information. Clock timing counts 
through a quartz oscillator running at a frequency of 32,768 kHz. This 
relatively slow IC 1s controlled through a PAL (programmable logic array). 


All clock registers lie in the address area of the processor, offering a simple 
to read and accurate clock. The Mega ST's operating system and XBIOS 
functions determine theimselves whether the clock time is taken from the 
keyboard processor, or whether the hardware clock is available at all. 
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4.5 Blitter chip demonstration programs 


This section contains programs demonstrating some of the blitter chip's 
abilities. 


This sample program moves the screen memory to another location. The 
function blit is universal, however, you can blit any RAM. Try the program 
as a test only. The main purpose of this program is to show how to 
establish screen areas (forms) and pixel coordinates for the individual 
registers of the blitter. This program directly accesses the blitter, and must 
run in 68000 supervisor mode. If you attempt to run the program in user 
mode, a bus error occurs. 


blitter equ S£f£8a00 

; blitter register offsets 
halftone equ 0 

src _ xinc equ $20 

src _yinc equ $22 

src_addr equ $24 

ENDMASK1 EQU $28 

endmask2 equ $2a 

endmask3 equ S$2c 

dst_xinc equ $2e 

dst_yinc equ $30 

dst_addr equ $32 

x count equ $36 

y count equ $38 

hop equ $3a 

op equ $3b 

line num equ $3c 

skew equ $3d 

; blitter register flags 
flinebusy equ 7 sbusy bit 
; mask blitter register bit 
mhop src equ $02 shalf-tone operation: source 
mskewfxsr equ $80 sfxsr mask 
mskewnfsr equ $40 snfsr mask 
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mlinebusy equ $80 sbusy mask 
physbase equ 2 s;get screen address 
xbios equ 14 
demo: 

lea para, a4 

move #physbase,- (sp) 

trap #xbios 


addq.1 #2,Sp s;get screen address 


move.1 dO,src_form(a4) ;screen acts as 
move. d0,dst_ form(a4) ;source and destination 
moveq #2,a0 32 bytes offset 
move dO, src_nxwd (a4) sto next word in 
move dO,dst_ nxwd(a4) same color plane 
moveq #80,d0 ;one line is 80 bytes long 
move dO,srce _ nxln(a4) ; (monochrome mode) 
move d0,dst_ nxln(a4) 
moveq #2,d0 ,;offset to next color plane 
move d0,src_nxpl (a4) j;not used in 
move dO,dst_nxpl (a4) s;monochrome mode 
move #25,src_xmin (a4) ;xl-coordinate source 
move #34,src_ymin(a4) syl-coordinate source 
move #220,dst_xmin(a4) ;xl-coordinate destination 
move #234,dst_ymin (a4) ;yl-coordinate destination 
move #77,width (a4) s;width in pixels 
move #50,height (a4) s;height-pixels (number of lines) 
move #1,planes (a4) ;monochrome 
jJsx blit it saccess blitter 
rts ; ready 
para dc.w 5 BE ;room for parameter block 
; end maskn 
lf endmask: 
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dc.w 


rt _endmask: 


-e 


src_ form 
src _nxwd 
src _nxln 
src_nxpl 
sre xmin 
src_ymin 


dst form 
dst nxwd 
dst _nxln 
dst_nxpl 
dst _xmin 
dst ymin 


width 
height 


planes 


ot We i oe Bo 


dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 


sffff 


S7Tfff 
S3fff 
vale 
SOffE 
SO7fE 
SO3ff 
SO1fE 
SOOff 
SOO7TE 
SOO3f 
SOO1E 
SOOOf 
$0007 
$0003 
$0001 
$0000 


input: pointer to 34-byte parameter block in a4 


equ 
equ 
equ 
equ 
equ 
equ 


equ 
equ 
equ 
equ 
equ 
equ 


equ 


equ 
equ 


lea 


sbase address source memory form 
;offset next word in source 
source form width 

;offset between source planes 
;source xl 

source yl 


s;base address dest memory form 
;offset next word in dest 
;dest form width 

s;offset between dst planes 
s;dest xl 

s;dest yl 


s;width in pixels 
sheight in pixels 
snumber of planes 


blitter,a5 
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SSS SSS ssh SSS SSS 


we 


compute xmax from xmin and width 


move 
subq 


move 
move 
add 


move 
move 
add 


moveq 


move 
and 
add 
move 


move 
and 
add 


move 
not 


width (a4) ,d6 
#1,d6 


src_xmin(a4),d0 
d0,dl 
d6,dl 


dst xmin(a4),d2 
d2,d3 
d6,d3 


#S£,d6 


d2,da4 
d6,d4 
d4,d4 
lf endmask (pc,d4) ,d4 


o3, a3 
d6,d5 
d5,d5 


rt endmask (pc,d5) ,d5 
d5 


calculate skew 
((dst_ xmin mod 16) - (src_xmin 


determine FXSR and NFSR 


3 bit index in table 


bit 0 


op 5 wae | 


bit 2 


move 


O src _xmin mod 16 >= 
1 src _xmin mod 16 > 


swidth -1 


;src_xmax 


;dst_xmax 
s;mod 16 mask 


sdst_xmin 

;dst_xmin mod 16 

s;pointer to left end mask table 
;left end mask 


;dst xmax 

;dst_xmax mod 16 

s;pointer to right end mask 
stable 

s;inverted left end mask 
;right end mask 


mod 16)) mod 16 


dst_xmin mod 16 
dst _xmin mod 16 


O src xmax/16 - src_xmin/16 <> dst_xmax/16 - 


dst_xmin/16 


O src xmax/16 - src_xmin/16 <> dst_xmax/16 - 


dst _ xmin/16 


O dst span equals several words 


1 dst span equals one word 


d2,d7 ;dst_xmin 
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and d6é,d7 ;dst_xmin mod 16 

and aod, d6 ;src_xmin mod 16 

sub d6é,d7 ;dst_xmin mod 16 - sre xmin mod 16 
; 2.2 CY =" 3 - ey @) 

clr dé ;delete index in table 

addx d6é,d6 s;cy after bit 0 

lsr #4,d0 ;srce_xmin / 16 

lsr #4,d1 ssrc_xmax / 16 

sub d0,dl s;src_span - l 

lsr #4,da2 ;dst_xmin / 16 

lsr #4,c3 ;dst_xmax / 16 

sub a2,a3 fast. span. - 1 

bne set _endmask 
; 8 
; if dst span = one word, both endmasks stand in endmask 1 
; the blitter ignores endmask 2 

and d5,d4 

addg #4,d6 3706 bit 2 = 1 one word destination 


set _endmask: 


of source und dest words 


1 = 1 equal number of 


of words in dest line 


move d4,endmaskl1 (a5) ;left endmask 
move #Sffff,endmask2 (a5) ;middle endmask 
move a5,endmask3 (a5) s;right endmask 
cmp al; a3 s;number 
;equal? 
bne set count 7no 
addg #2,c6 306 bit 
; words 
set count: 
move a3,da4 
addgq #1,c4 ;number 
move gd4,x count (a5) 
; determine source start address 
; src form + (src_ymin * sre nxln) * (srce_xmin/16 * src_nxwd) 
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move .1 src_form(a4),a0 3;aQ -> start sre form 
move src _ymin(a4),d4 ;offset in lines to ymin 
move src_nxln(a4),d5 slength sre line 
mulu a5,da4 
add.l d4,a0 7aO0 -> (0, ymin) 
move src_nxwd(a4),d4 ;offset of next word 
move d4,srce_xinc(a5) 
mulu d4,d0 
add.1 dod, a0 3;a0 -> first word (xmin, ymin) 
mulu d4,dl source line length in bytes 
sub d1,d5 
move d5,sre_yinc(a5) ;offset next end line beginning 
; compute destination start address 
move.1 dst form(a4),al sal -> start dst form 
move dst _ymin(a4) ,d4 
move dst_nxln(a4),d5 
mulu d5,d4 
add.1l qd4,al 
move dst nxwd(a4),d4 
move d4,dst_xinc(a5) 
mulu d4,da2 
add.l d2,dal 
; compute dst yinc 
mulu ad4,d3 
sub a3,da5 
move d5,dst_yinc(a5) s;destination y increment 
and.b #S£,a7 
or.b skew flags(pc,d6),d/ ;skew-flags from table 
move .b a7, skew(a5) jin blitter 
move.b #mhop src,hop(a5) s;half-tone operation: source only 
move.b #3,0p (a5) ;replace mode 
lea line num(a5),a2 s;pointer to line number register 
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move .b #flinebusy,d2 
move planes (a4),d/ 
bra begin 

skew flags: 
ee.) mskewnfsr 
2 (oN 8 mskewfxsr 
dc.b 0 
dc.b mskewnfsrt+mskewfxsr 
adc.) 0 
9 mskewfxsr 
dc.b 0 
Go, 0 


next plane: 


move.l a0Q,src_addr (a5) 
move.1 al,dst_addr (a5) 
move height (a4),y_ count (a5) 
move .b #mlinebusy, (a2) 
add src_ nxpl(a4),a0 
add dst _nxpl(a4),al 

restart: 
bset d2, (a2) 
nop 
bne restart 

begin dbra d7,next_plane 
rts 

end 


busy bit after d2 
s;number of bitplanes 


jload source address 
sload destination address 
s;number of lines 
;start blitter 


;start next src plane 
;start next dst plane 


s;restart blitter 
snot ready yet? 


snext bitplane 


Here are some extremely interesting sample programs for the BITBLT 


line-A command. 


The first example defines a monochrome picture and copies it to a 
monchrome screen. The picture should appear on the screen starting at the 
coordinates X = 200 and Y = 100. This replaces the original screen contents 
using the replace mode. No raster is used, so the raster address is set to 


zero. The program looks like this: 
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: Ket KK KK HK KK KKH KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KK KKK KKK KKK KK KKK 


; bitblt demo * 


; copy one-color source range to monochrome screen * 
PRK KKK KK KEKE KKK KKEKKKKEKKEKKKEKKKEKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK KKKKKKKK 


DLCHIC equ $a007 ;Op code 


b width equ 
b height equ 


0 s;width in pixel 
2 sheight in pixel 
planes equ 4 snumber of colorplanes 
rg. col equ 6 s;foreground color 
8 
0 


bg col equ sbackground color 


op tab equ 1 ;logical operations 
s_xmin equ 14 #x-coordinate in source 
s_ymin equ 16 sy-coordinate in source 
s form equ Lo s;address of source 
Ss nxwd equ 22 ;offset of next word in source 
s nxln equ 24 ;offset of next line in source 
Ss nxpl equ 26 soffset of next colorplane in source 
d xmin equ 28 ;x-coordinate in destination 
d ymin equ 30 sy-coordinate in destination 
d form equ 32 ;address of destination 
d nxwd equ 36 ;offset of next word in destination 
d nxln equ 38 ;offset of next line in destination 
d nxpl equ 40 soffset of next colorplane in 
;destination 
p_addr equ 42 saddress of raster used 
p nxin equ 46 ;offset of next line in raster 
p nxpl equ 48 soffset of next colorplane in raster 
p_mask equ 50 ;raster index mask (number of lines) 
physbase equ 2 
xbios equ 14 
do blit lea para(pc) ,a6 ;pointer to parameter block 
move #92,b width (a6) s;width in pixel 
move #52,b height (a6) sheight in pixel 
move #1,planes (a6) ;monochrome 
move #1,{fg col{a6) ;foreground color 
move #0,bg_ col (a6) s;background color 
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para: 


me -e 


source 


move.l 


move 
move 


move. 


move 
move 


move 


move. 


92 
22 


#503030303,0op tab(a6) ;replace mode 


#0,S_xmin (a6) 
#0,S_ ymin (a6) 


#source,s_ form(a6é) 


#2,22 (a6) 
#12,s nxln(aé) 


#2,S nxpl(aé) 


#200,d_xmin (a6) 
#100,d_ymin (a6) 


#physbase,-(sp) 
#xbios 

#2,Sp 

d0,d_ form(aé) 
#2,d_nxwd (a6) 


#80,d_nxln(a6) 
#2,da_nxpl (a6) 


p_addr (a6) 


transfer source data 
supper left corner of source 


;source address 


s;2 byte offset of next word 
#80 byte offset of next 
sline 

#2 byte offset of next 
;colorplane 


screen is destination 
;x-coordinate of screen 
s;y-coordinate of screen 


sget screen address 


jas destination address 


#2 byte offset of next word 
380 byte offset of next line 
#2 byte offset of next 
;colorplane 


sno raster used 

HItSb1it execute bitblt 
76 376 byte parameter block 

width of source in pixels 


height of source in pixels 


SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
S579; 90000, 99090, PIDOD; POO oy 00 
SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
$5599) S205), G20s0; FIDO0; sod, SO o0U 
SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
$5555, $5555, $5555, $5FD5,55555,959590 
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end 


SLES EC LCE LCL SELL LLC LCL LC ELC EC EC KLE KLE KR EEE REECE RE KEE EEE EEE ESE 


SAAAA, SAAAA, SAAAA, $BO6A, SAAAA, SAAAO 
$5555, $5555, $55FF, $E03D, $5555, $5550 
SAAAA, SAAAA, $AB83, SOO0A, SAAAA, SAAAO 
$D555,$5555, $5701, $FFEF, $5555, $5550 
SEAAA, SAAAA, $ACO0, $002A, SAAAA, SAAAO 
$F555,$5555, $SFF7, $F7A7, $5555, $5550 
SFPAAA, SAAAA, $B00C, $18AE, SAAAA, SAAAO 
SFD55,$5555,$7FF8, $0OE9B, $5555, $5550 
SEOAA, SAAAA, $C000, $02B2, SAAAA, SAAAO 
$6555,$5555, SFFFF, $FC63, $5555, $5550 
$B2AA, SAAAB, $0000, $04C6, SAAAA, SAAAO 
$3555, $5555, $0700, $058B, $5555, $5550 
$9AAA, SAAAB, $0880, $0712, SAAAA, SAAAO 
$5955, $5555, SOF80, $0627, $5555, $5550 
SA2AA, SAAAB, $0880, $044A, SAAAA, SAAAO 
$5555, $5555, $0880, $0493, $5555, $5550 
SAAAA, SAAAB, $0000, $0522, SAAAA, SAAAO 
$5555,$5555, $03FC, $0647, $5555, $5550 
SAAAA, SAAAB, $0204, $048C, SAAAA, SAAAO 
$5555, $5555, $0204, $0519, $5555, $5550 
SAAAA, SAAAB, $03FC, $0632, SAAAA, SAAAO 
$5555, $5555, $0000, $0465, $5555, $5550 
SAAAA, SAAAB, $0000, $04CA, SAAAA, SAAAO 
$5555,$5555, $060C, $0595, $5555, $5550 
SAAAA, SAAAB, SOFF8,$072A, SAAAA, SAAAO 
$5555, $5555, $0000, $0655, $5555, $5550 
SAAAA, SAAAB, $0000, $04AA, SAAAA, SAAAO 
$5555, $5555, $0000, $0555, $5555, $5550 
SAAAA, SAAAB, SFFFF, $FEAA, SAAAA, SAAAO 
$5540, $0000, $0000, $0000, $0000, $1550 
SAAAO, $0000, $0000, $0000, $0000, SOAAO 
$5543, $C71E,$49EF, $9CF9, $C722, $1550 
SAAA2, $2220, $5202, $2220, $88B2, SOAAO 
$5542,$221C, $61C2, $3E20, $88AA, $1550 
SAAA2, $2202, $5022, $2220, $88A6, SOAAO 
$5543, $C73C, $4BC2, $2221, $C722, $1550 
SAAAO, $0000, $0000, $0000, $0000, SOAAO 
$5540, $0000, $0000, $0000, $0000, $1550 
SAAAO, $0000, $0000, $0000, $0000, SOAAO 
$5555, $5555, $5555, $5555, $5555, $5550 
SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
$5555, $5555, $5555, $5555, $5555, $5550 
SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
$5555,$5555, $5555, $5555, $5555, $5550 
SAAAA, SAAAA, SAAAA, SAAAA, SAAAA, SAAAO 
$5555, $5555, $5555, $5555, $5555, $5550 


488 


Abacus Software Atari ST Internals 


The next example tests out raster use. A raster is basically a graphic area 
which combines with a source range through a logical AND, and the desired 
logical operation is copied to the destination range. The comparison of the 
source range with the raster naturally occurs within the BITBLT function. 
The source range itself stays independent. 


p_mask and p addr correspond to the variables patptr and _patmsk 
through the function $A004, HORIZONTAL LINE. The variable p_nxin 
gives the offset for the next line of the raster, and must be an even number, 
so a line from any number of 16 bit words must coincide, as well as source 
and destination. 


A raster can usually be multicolor. The individual bitplanes must then be 
overlapped word for word as described in the beginning of this chapter. The 
raster index mask (p_mask) gives which raster line should be combined 
with the source line. From the source line the number of raster line comes 
from AND and p_ mask. This is the usual count: 


Raster Lines p mask 


2 1 
4 - 
8 7 
16 15 


The blitter has 16 registers of 16 bits into which a raster can be loaded. 


This sample program is almost identical to the earlier BITBLT demo. Just 
replace the material at the do_blit and raster labels with the coding 
below. Then save the new version of BITBLT under another name. 


CK KK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKKKEKKEKKKKKEKK 


* 


a 
co 


, 
; bitblt demo changes * 
; copy one-color range to monchrome screen using a raster * 
> * 
PRK KKK KKK KKK KKK KKK KK KKKEKKKKKKK KKK KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KK KK 
do blit lea para(pc),aé ;pointer to parameter block 

move #92,b width (a6) s;width in pixels 

move #52,b height (a6) sheight in pixels 

move #1,planes (a6) ;monochrome 
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SSS sss sss elses essences 


move #1,fg col (a6) sforeground color 
move #0,bg col (a6) background color 
move. 1 #503030303,op tab(a6é) ;replace mode 
; transfer source data 
move #0,s xmin (a6) ;source from upper left corner 
move #0,s ymin (a6) 
move. #source,s form(a6) ;source address 
move #2,S nxwd (a6) #2 byte offset to next word 
move #12,s nxln(aé) ;80 byte offset to next line 
move #2,s nxpl (a6) #2 byte offset - next color plane 
; dest is screen 
move #200,d_ xmin (a6) ;x-coordinate on screen 
move #100,d_ ymin (a6) ;y-coordinate on screen 
move #tphysbase,-(sp) 
trap #xbios ;get screen address 
addq. #2,Sp 
move. d0,d_ form(a6é) suse as dest address 
move #2,d_ nxwd (a6) 72 byte offset of next word 
move #80,d_ nxln(a6é) 780 byte offset to next line 
move #2,d_nxpl (a6) 32 byte offset of next color 
;plane 
move #raster,p addr(a6) ;use raster 
move #2,p nxln (a6) ;offset of next raster line 
move #0,p nxpl (a6) single color raster 
move #1,p mask (a6) s;raster index mask 
dc.w bitblt ;execute bitblt 
rts 
align 
raster dc.w %$1010101010101010 ;first raster line 
dc.w %$0101010101010101 ;second raster line 
para; ds.b 76 ;76-byte parameter block 


; source and rest of original program follow.... 


Every other pixel is deleted, giving us a raster. 
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Index 

address bus 7,8 

asynchronous bus control 8-9 
ADDRESS STROBE (AS) 8 
DTACK 9-12 
LOWER DATA STROBE (LDS) 8 
READ/WRITE (R/W) 8 
UPPER DATA STROBE (UDS) 

Asynchronous Communications Interface Adapter (ACIA) 41-47,62-63 
pins 41-44 
registers 45-47 

BANK 55 

Basic Input Output System (BIOS) 152-163,245,250 
listing 271-461 

BCD—-see Binary Coded Decimal 

BERR 11-15 


BG—see Bus Grant 
BGACK—see Bus Grant Acknowledge 


BGO—see Bus Grant Out 

Binary Coded Decimal (BCD) 4 
BIlOS—see Basic Input Output heer 

BLANK 15 
Blitter chip 204-205,469-476,484-496 
Bus Grant (BG) 10,13 
Bus Grant Acknowledge (BGACK) 10,13 
Bus Grant Out (BGO) 13 
Bus Request (BR) 1013 
cartridge slot | 96-98 
Centronics interface 88-89 
CLK 11 
data bus 7 
data registers 4 
Data Request (DR) 22 
DE—see Display Enable 

Digital Research 105 


Direct Memory Access (DMA) 8-9,12-13,18-19,25,58-59, 101-102 
Display Enable (DE) 15 


DMA—see Direct Memory Access 
DR—see Data Request 
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a 


exception vectors 235-237 


FDC—see Floppy Disk Controller 


Floppy Disk Controller (FDC) 20-27 
Command Register (CR) 24 
Data Register (DR) 24 
Sector Register (SR) 24 
Status Register (STR) 24 
Track Register (TR) 24 
floppy disk interface 99-100 
GEM graphics 206-234 
high-res 207-210 
line-A opcodes 227-234 
line-A variables 224-226 
lo-res 206-209 
medium-res 205-207 
GEM graphic commands 211-224 
BITBLT 215-217 
COPY RASTER FORM 224-225 
CONTOUR FILL 223-224 
DRAW SPRITE 222-223 
FILLED POLYGON 214-215 
FILLED RECTANGLE 213-214 
GET PIXEL 211 
HIDE CURSOR 221 
HORIZONTAL LINE 213 
Initialize 211 
LINE 212 
PUT PIXEL 211 
SHOW MOUSE 220 
TEXTBLT 217-222,232-235 
TRANSFORM MOUSE 221,230-231 
UNDRAW SPRITE 221-222,221-222 
GEMDOS 105-151, 245 
functions 106-151 
error messages 151 
GLUE 13-15, 18,69 
HALT 1T,12 
HSYNC 15 
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IACK 13 
integrated circuits 3-63 
INTEL 3 
interrupts 7,10,240-244 
I/O registers 55-63 
ACIAs 62 
DMA/Disk Controller 58-59 
keyboard 62 
MFP 68901 60-61 
MIDI 62 
sound chip 59-60 
Video Display Register 56-58 
keyboard control 67-71,74-84 
line-F emulator 238-239 
longword 6 
Memory Management Unit(MMU) 11,13,15-16,18,55 
memory maps 62-63 
MFP 68901—see Multi-Function Peripheral 
MFPINT 13 


MIDI—see Musicial Instrument Digital Interface 
MMU—see Memory Management Unit 


Motorola 68000 microprocessor 3-12,258-270 
instruction set 258-270 
mouse 71-74 
MS-DOS 106, 186 
Multi-Function Peripheral(MFP 68901)  28-40,60-61,90,171,242-244 
Active Edge Register(AER) 32 
connections 28-32 
Data Direction Register(DDR) 32 
General Purpose I/O Interrupt Port(GPIP) 32 
Interrupt Enable Register(IERA,IERB) 33 
Interrupt In-Service Register(ISRA,ISRB) 34 
Interrupt Mask Register IMRA,IMRB) 34 
Interrupt Pending Register(IPRA,IPRB) 33-34 
Receiver Status Register(RSR) 38-39 
registers 32-40 
Synchronous Character Register(SCR) 37 
Timer A/B Control Register(TACR,TBCR) 35 
Timers C and D Control Register(TCDCR) 36 
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neem emer 


Timer Data Registers (TADR,TBDR,TCD 
Transmitter Status Register(T SR) 


UCR/USART 
UDR/USART 
Vector Register(VR) 


Musical Instrument Digital Interface(MIDI) 


NMI—see Non-Maskable Interrupt 
Non-Maskable Interrupt (NMI) 


operating system 


37 
39-40 
37-38 

40 

34 


93-95,177 


6,13,240 
105 


PSG (Programmable Sound Generator) —see YM-2149 Sound Generator 


RESET 
RS-232 interface 


SHIFTER 

Status register 
supervisor mode 
Synchronous bus control 


Valid Memory Address (VMA) 
Valid Peripheral Address (VPA) 


system fonts 
system variables 


Tramiel Operating System (TOS) 


UNIX 
user mode 


video interface 
VSYNC 
VT52 emulator 


WD 1772 
word 
word access 


XBIOS 
YM-2149 Sound Generator 
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11-12 


90-92,243-244 
13,15,17,18 
6 


4,6,7,235 
9 

9 

9 

9,10 


465-466 
250-257 


105 


106 
4,6,7,235 


85-87 
15 
245-249 
20-27 

fi 

8 
164-205 


48-54 


